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Logstash 
入 门 示例 

下 载 安 装 

hello world 

配置 语法 

plugin 的 安装 

长 期 运行 

插件 配置 

input 配 置 
file 
stdin 
syslog 
tcp 

codec 配 置 
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netflow 
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mutate 
ruby 
split 
elapsed 
output & 
elasticsearch 
email 
exec 
file 
nagios 
statsd 
stdout 
tcp 
hdfs 
场景 示例 
nginx 访 问 日 志 
nginx 错 误 日 志 
postfix 日 志 
ossec A & 
windows & % H & 
Java A & 
MySQL 3 18 H & 
性 能 与 测试 
generator 方 式 
logstash-input-heartbeat 方 式 
jmx 局 动 参数 方式 
API 方 式 
扩展 方案 


通过 redis 传 输 
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通过 kafka 传 输 
AIX 平台 上 的 logstash-forwarder-java 
rsyslog 
nxlog 
heka 
fluent 
Message::Passing 

源码 解析 
pipeline 流 程 
Event 的 生成 

插件 开发 
utmp 插 件 示 例 

Beats 

filebeat 

packetbeat 网 络 流量 分 析 

metricbeat 

winlogbeat 

ElasticSearch 

架构 原理 
segment、buffer 和 translog 对 实时 性 的 影响 
segment merge 对 写 入 性 能 的 影响 
routing 和 replica 的 读 写 过 程 
shard 的 allocate 控 制 
自动 发 现 的 配置 

接口 使 用 示例 
增删 改 查 操作 
搜索 请 求 
Painless 脚 本 
reindex 接 口 

性 能 优化 
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curator 工 具 
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计划 内 停机 升级 的 操作 流程 
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rollover 和 shrink 
Ingest 节 点 
Hadoop 集成 

spark streaming X: Z 
权限 管理 

Shield 
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监控 方案 
监控 相关 接口 
集群 健康 状态 
节点 状态 
索引 状态 
任务 管理 
cat 接口 的 命令 行使 用 
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实时 bigdesk 方 案 
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推荐 阅读 
合作 名 单 
捐赠 名 单 


1.5.9.3 
1.5.9.4 
1.5.9.5 
1.5.10 
1.5.10.1 
1.5.10.2 
1.5.10.3 
1.5.10.4 
1.5.10.5 
1.5.11 
1.5.11.1 
1.5.11.2 
1.5.11.3 
1.5.12 
1.6 
1.7 
1.8 
1.9 


Elastic Stack Æ /& ELK Stack 在 5.0 版 本 加 入 Beats 套件 后 的 新 称呼 。 


Elastic Stack 在 最 近 两 年 迅速 崛起 ， 成 为 机 器 数据 分 析 ， 或 者 说 实时 日 志 处 理 领 
域 ， 开 源 界 的 第 一 选择 。 和 传统 的 日 志 处 理 方案 相 比 ，Elastic Stack 具有 如 下 几 个 
优点 : 


e 处 理 方式 灵活 。Elasticsearch 是 实时 全 文 索引 ， 不 需要 像 storm 那样 预先 编程 
才能 使 用 ; 

e 配置 简 多 上手 。Elasticsearch 全 部 采用 JSON 接口 ，Logstash 是 Ruby DSL 
设计 ， et a a a da. 

e 检索 性 能 高 效 。 虽 然 每 次 查询 都 是 实时 计算 ， 但 是 优秀 的 设计 和 实现 基本 可 以 
达到 全 天 数据 查询 id 级 响应 ; 

e 集群 线性 扩展 。 不 管 是 Elasticsearch 集群 还 是 Logstash 集群 都 是 可 以 线性 扩 

e 前 端 操作 炫丽 。Kibana 界面 上 ， 只 需要 点 击 和 鼠标， 就 可 以 完成 搜索 、 聚 合 功 
能 ， 生 成 炫丽 的 仪表 板 。 


当然 ，Elastic Stack 也 并 不 是 实时 数据 分 析 界 的 灵丹妙药 。 在 不 恰当 的 场景 ， 反 而 
会 事倍功半 。 我 自 2014 年 初 开 QQ 群 交 流 Elastic Stack， 发 现 网 友 们 对 Elastic 
Stack 的 原理 概念 ， 常 有 误解 误 用 ; 对 实现 的 效果 ， 又 多 有 不 能 理解 或 者 过 多 期 户 
而 失望 之 处 。 更 令 我 惊奇 的 是 ， 网 友 们 广泛 分 布 在 传统 企业 和 互联 网 公司 、 开 发 和 
运 维 领域 、Linux 和 Windows 平台 ， 大 家 对 非 专 精 领域 的 知识 ， 一 般 都 缺乏 了 解 ， 
这 也 成 为 使 用 Elastic Stack 时 的 一 个 障碍 。 


为 此 ， 写 一 本 Elastic Stack 技术 指南 ， 帮 助 大 家 厘清 技术 细节 ， 分 享 一 些 实战 案 
ee = 一 大 心愿 。 本 书 大 体 完 工 之 后 ， 幸 得 机 械 工 业 出 版 社 华章 公司 青 
Bk * YA (ELK Stack 权威 指南 》 之 名 重修 完善 并 出 版 ， 有 意 收藏 者 欢迎 购买 。 


RAT E Stack， 虽 然 接触 较 旱 ， 但 本 身 专 于 web fe app 应 用 数据 方面 ， 动 
笔 以 来 ， 得 到 诸多 朋友 的 帮助 ， 详 细 贡 献 名 单 见 合作 名 单 。 此 外 ， 还 要 特别 感谢 曾 
oa ， 完 成 ES 在 国内 的 启蒙 式 分 享 ， 并 主办 ES 中 国 用 户 大 会 ; 吴 晓 刚 
(wood) 同 学 ， 积 极 帮 助 新 用 户 们 ， 并 最 早 分 享 了 携程 的 Elastic Stack 日 亿 级 规模 的 
实例 。 


欢迎 加 入 Elastic Stack 交流 QQ 群 : 315428175 。 


欢迎 捐赠 ， 作 者 支付 宝 账号 : rao.chenlin@gmail.com 
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Version 


2016-10-27 发 布 了 Elastic Stack 5.0 版 。 由 于 变动 较 大 ， 本 书 Git 仓库 将 master 
分 支 统 一 调整 为 基于 5.0 的 状态 。 


想 要 查阅 过 去 K3、k4、logstash-2.x 等 不 同 老 版 本 资料 的 读者 ， 请 下 载 ELK 
release : https://github.com/chenryn/ELKstack-guide-cn/releases/tag/ELK 


TODO 


限于 个 人 经 验 、 时 间 和 场景 ， 有 部 分 Elastic Stack 社区 比较 常见 的 用 法 介绍 未 完 


成 ， 


期 待 各 位 同好 出 手 。 罗 列 如 下 : 


es-hadoop 用 例 

beats 开发 

codec/netflow 的 详解 
filter/elapsed 的 用 例 
zeppelin 的 es 用 例 
kibana 的 filter 交 互 用 法 
painless 的 date 对 象 用 法 : 同比 环比 图 
significant text aggs 用 例 
cat nodeattrs 接 口 
timelion 保 存 成 panel 的 用 法 
regionmap 用 法 


e Time Series Visual Builder] X 
e Viewing Document Context 用 法 
e Dead Letter Queues} f4 
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第 一 部 分 Logstash 


Logstash is a tool for managing events and logs. You can use it to collect 
logs, parse them, and store them for later use (like, for searching). -- 
http://logstash.net 


Logstash 项 目 诞生 于 2009 年 8 月 2 日 。 其 作者 是 世界 著名 的 运 维 工 程 师 乔 丹 西 塞 
(JordanSissel)， 乔 丹 西 塞 当时 是 著名 虚拟 主机 托管 商 DreamHost 的 员工 ， 还 发 布 
过 非常 棒 的 软件 打包 工具 fpm， 并 主办 着 一 年 一 度 的 sysadmin advent 
calendar(advent calendar 文化 源 自 基督 教 氛围 浓厚 的 Perl 社区 ， 在 每 年 圣诞 来 临 
的 12 月 举办 ， 从 12 月 1 日 起 至 12 月 24 日 止 ， 每 天 发 布 一 篇 小 短文 介绍 主题 相 
关 技 术 )。 


小 贴 士 : Logstash 动手 很 旱 ， 对 比 一 下 ，scribed 诞生 于 2008 年 ，flume 诞生 于 
2010 年 ，Graylog2 诞生 于 2010 # > Fluentd 诞生 于 2011 年 。 


scribed 在 2011 年 进入 半死 不 活 的 状态 ， 大 大 激发 了 其 他 各 种 开源 日 志 收 集 处 理 框 
IK 865 2 Sh BHR * Logstash 也 从 2011 年 开始 进入 commit 密集 期 并 延续 至 今 。 


作为 一 个 系 出 名 门 的 产品 ，Logstash 的 身影 多 次 出 现在 Sysadmin Weekly + > € 
和 它 的 小 伙伴 们 Elasticsearch ^ Kibana 直接 成 为 了 和 商业 产品 p 人 
源 项 目 (乔丹 西 塞 曾经 在 博客 上 承认 设计 想法 来 自 AWS 平台 上 最 大 的 第 三 方 日 志 服 
务 商 Loggly， 而 Loggly 两 位 创始 人 都 曾 是 Splunk 员工 )。 


2013 年 ，Logstash 被 Elasticsearch 公司 收购 ，ELK Stack 正式 成 为 官方 用 语 ( 随 
着 beats 的 加 入 改名 为 Elastic Stack)。Elasticsearch 本 身 也 是 近 两 年 最 受 关注 的 
大 数据 项 目 之 一 ， 三 次 融资 已 经 超过 一 亿美 元 。 在 Elasticsearch 开发 人 员 的 共同 
努力 下 ，Logstash 的 发 布 机 制 ， 插 件 架构 也 您 发 科学 和 合理 。 


FL RK TAL 


志 收 集 处 理 框架 这 么 多 ， 像 scribe 是 facebook He > flume 是 apache 基金 会 项 
目 ， 都 算 声 名 赫赫 。 但 logstash 因 乔 丹 西 塞 的 个 人 性 格 ， 形 成 了 一 套 独 特 的 社区 文 
化 。 每 一 个 在 google groups 的 logstash-users 组 里 问答 的 人 都 会 看 到 这 么 一 名 
18 


Remember: if a new user has a bad time, it's a bug in logstash. 


Pr VA > logstash 是 一 个 开放 的 ， 极 其 互助 和 友好 的 大 家 庭 。 有 任何 问题 ， 尽 管 在 
github issue > Google groups > Freenode#logstash channel 上 发 问 就 好 | 


基础 知识 


什么 是 Logstash? 为 什么 要 用 Logstash? 怎么 用 Logstash ? 


i OMS 来 回答 这 个 问题 ， 或 许 不 完整 ， 但 是 足够 讲述 一 些 基础 概念 。 跟 着 我 们 安 
一 步 步 来 ， 你 就 可 以 成 功 的 运行 起 来 自己 的 第 一 个 logstash 了 。 


y 
itt 
GR 


ua 


不 会 立刻 来 展示 logstash 配置 细节 或 者 运用 场景 。 我 认为 基础 原理 和 语法 的 
该 更 加 重要 ， 这 些 知识 未 来 对 你 的 帮助 绝对 更 大 | 


一 


PEVA > IŽ RTR AUTI E | 


J+ 


TAX 


直接 下 载 官方 发 布 的 二 包 的 ， 可 以 访问 
https://www.elastic. a 页 面 找 对 应 操作 系统 和 版 本 ， 点 击 下 载 
即 可 。 不 过 更 推荐 使 用 软件 仓库 完成 安装 。 


E 
ERK 
Se 时 在 一 些 很 老 的 操作 系统 上 运行 Logstash， 那 你 只 能 用 源 代 码 包 部 署 
， 记 住 要 自己 提前 安装 好 Java: 


yum install java-1.8.0-openjdk 
export JAVA_HOME=/usr/java 


软件 仓库 的 配置 ， 主 要 两 大 平台 如 下 
Debian 平台 


wget -0 - http://packages.elasticsearch.org/GPG-KEY-elasticsearc 
h | apt-key add - 

cat >> /etc/apt/sources.list ««EOF 

deb http://packages.elasticsearch.org/logstash/5.0/debian stable 
main 

EOF 

apt-get update 

apt-get install logstash 


Redhat 平台 


rpm --import http://packages.elasticsearch.org/GPG-KEY-elasticse 
arch 

cat > /etc/yum.repos.d/logstash.repo ««EOF 

[logstash-5.0] 

name=logstash repository for 5.0.x packages 
baseurl=http://packages.elasticsearch.org/logstash/5.0/centos 
gpgcheck=1 
gpgkey-http://packages.elasticsearch.org/GPG-KEY-elasticsearch 
enabled-1 

EOF 

yum clean all 

yum install logstash 


Hello World 


和 绝 大 多 数 IT 技术 介绍 一 样 ， 我 们 以 一 个 输出 "hello world" 的 形式 开始 我 们 的 
logstash 学 习 。 


运行 
在 终端 中 ， 像 下 面 这 样 运行 命令 来 启动 Logstash 进程 


# bin/logstash -e 'input{stdin{}}output{stdout {codec=>rubydebug} 
} 1 


然后 你 会 发 现 终端 在 等 待 你 的 输入 。 没 问题 ， 敲 入 Hello World， 回 车 ， 然 后 看 看 
会 返回 什么 结果 ! 
结 

{ 

"message" => "Hello World", 
Y@versione > Ma, 
"@timestamp" => "2014-08-07T10:30:59.937Z", 
"host" => "raochenlindeMacBook-Air.local", 
y 


没 错 ! 你 搞定 了 | 这 就 是 全 部 你 要 做 的 。 


解释 


每 位 系统 管理 员 都 肯定 写 过 很 多 类 似 这 样 的 命 cat randdata | awk 
'{print $2)' | sort | uniq -c | tee sortdata 。 这 个 管道 符 | 可 以 算是 


Linux 世界 最 伟大 的 发 明之 一 ( 另 一 个 是 "一切 蛋 文件 ”)。 


Logstash 就 像 管道 符 一 样 ! 


你 输入 (就 像 命令 行 的 cat ) 数 据 ， 然 后 处 理 过 滤 (就 像 awk RA uniq 之 类 ) 
数据 ， 最 后 输出 (就 像 tee ) 到 其 他 地 方 。 


当然 实际 上 ，Logstash 是 用 不 同 的 线程 来 实现 这 些 的 。 如 果 你 运行 top 命令 然 
ERT H 键 ， 你 就 可 以 看 到 下 面 这 样 的 输出 : 


PID USER PR NI VIRT RES SHR S 96CPU %MEM TIME+ COM 
MAND 
21401 root 16 © 1249m 303m 10m S 18.6 0.2 866:25.46 |wo 
rker 
21467 root 15 © 1249m 303m 10m S 3.7 0.2 129:25.59 >el 
asticsearch. 
21468 root 15 © 1249m 303m 10m S 3.7 0.2 128:53.39 >el 
asticsearch. 
21400 root 15 © 1249m 303m 10m S 2.7 0.2 108:35.80 «fi 
le 
21403 root 15 © 1249m 303m 10m S 1.3 0.2 49:31.89 »ou 
tput 
21470 root 15 © 1249m 303m 10m S 1.0 0.2 56:24.24 >el 
asticsearch. 


小 贴 士 : logstash (Ris 2$ 84 26 4k ^- AAP RT ZF ABT xx > TRAY [xx 


数据 在 线程 之 间 以 事件 的 形式 流传 。 不 要 叫 行 ， 因 为 logstash 可 以 处 理 多 行事 
件 。 


Logstash 会 给 事件 添加 一 些 额 外 信息 。 最 重要 的 就 是 @timestamp， 用 来 标记 事 
件 的 发 生 时 间 。 因 为 这 个 字段 涉及 到 Logstash 的 内 部 流转 ， 所 以 必须 是 一 个 joda 
对 象 ， 如 果 你 尝试 自己 给 一 个 字符 串 字段 重 命名 为 @timestamp 的 话 ，Logstash 
会 直接 报错 。 所 以 ， 请 使 用 filters/date 插件 来 管理 这 个 特殊 字段 。 


此 外 ， 大 多 数 时 候 ， 还 可 以 见 到 另外 几 个 : 


1. host 标记 事件 发 生 在 哪里 。 
. type 标记 事件 的 唯一 类 型 。 
3. tags 标记 事件 的 某 方 面 属 性 。 这 是 一 个 数组 ， 一 个 事件 可 以 有 多 个 标签 。 


你 可 以 随意 给 事件 添加 字段 或 者 从 事件 里 删除 字段 。 事 实 上 事件 就 是 一 个 Ruby 对 
象 ， 或 者 更 简单 的 理解 为 就 是 一 个 哈 希 也 行 。 


小 贴 士 : 每 个 logstash 过 滤 插 件 ， 都 会 有 四 个 方法 叫 add tag , remove tag , 
add field 和 remove field 。 它 们 在 插件 过 滤 匹 配 成 功 时 生效 。 


推荐 阅读 


e 《the life of an event》 官 网 文档 
e (life of a logstash event? Elastic(ON) 上 的 演讲 


w ` ` 
配置 语法 


语法 


jag 
ye 


Logstash 社区 通常 习惯 用 shipper > broker 和 indexer X 4% xt 4 iP A A 
自 的 角色 。 如 下 图 : 





不 过 我 见 过 很 多 运用 场景 里 都 没有 用 logstash 作为 shipper， 或 者 说 没有 用 
elasticsearch 作为 数据 存储 也 就 是 说 也 没有 indexer。 所 以 ， 我 们 其 实 不 需要 这 些 
概念 。 只 需要 学 好 怎么 使 用 和 配置 logstash 进程 ， 然 后 把 它 运用 到 你 的 日 志 管 理 架 
构 中 最 合适 它 的 位 置 就 够 了 。 


语法 

Logstash 设计 了 自己 的 DSL 一 一 有 点 像 Puppet 的 DSL， 或 许 因 为 都 是 用 Ruby 
语言 写 的 吧 一 包括 有 区 域 ， 注 释 ， 数 据 类 型 (布尔 值 ， 字 符 囊 ， 数 值 ， 数 组 ， 哈 
希 )， 条 件 判 断 ， 字 段 引 用 等 。 

区 段 (sectiom) 


Logstash 用 {} 来 定义 区 域 。 区 域内 可 以 包括 插件 区 域 定 义 ， 你 可 以 在 一 个 区 域 
内 定义 多 个 插件 。 插 件 区 域内 则 可 以 定义 键 值 对 设置 。 示 例如 下 


19 


input { 


stdin {} 
syslog {} 
} 
数据 类 型 


Logstash 支持 少量 的 数据 值 类 型 : 


e bool 


debug => true 


e string 


host => "hostname" 


e number 


port => 514 


e array 


match => ["datetime", "UNIX", "ISO8601"] 


e hash 
options => { 


key1 => "valuei", 
key2 => "value2" 


注意 : 如 果 你 用 的 版 本 低 于 1.2.0， 哈 希 的 语法 跟 数 组 是 一 样 的 ， 像 下 面 这 样 写 : 


match => [ "fieldi", "patterni", "field2", "pattern2" ] 


字段 引用 (field reference) 


字段 是 Logstash::Event 对 象 的 属性 。 我 们 之 前 提 过 事件 就 像 一 个 哈 硕 一 样 ， 
所 以 你 可 以 想象 字段 就 像 一 个 键 值 对 。 
小 贴 士 : 我 们 叫 它 字段 ， 因 为 Elasticsearch 里 是 这 


这 
如 果 你 想 在 Logstash 配置 中 使 用 字段 的 值 ， 只 需要 把 字段 的 名 字 写 在 中 括号 [] 
里 就 行 了 ， 这 就 叫 字段 引用 。 


对 于 网 套 字 段 (也 就 是 多 维 哈 希 表 ， 或 者 叫 哈 希 的 哈 希 )， 每 层 的 字段 名 都 写 在 [] 
里 就 可 以 了 。 比 如 ， 你 可 以 从 geoip 里 这 样 获取 longitude 值 (是 的 ， 这 是 个 策 办 
法 ， 实 际 上 有 单独 的 字段 专门 存 这 个 数据 的 ) : 


[geoip][location][0] 


小 贴 士 : logstash 的 数组 也 支持 倒序 下 标 ， 即 [geoip][location][-1] TAR 
取 数 组 最 后 一 个 元 素 的 值 。 


Logstash 还 支持 变量 内 插 ， 在 字符 串 里 使 用 字段 引用 的 方法 是 这 样 : 


"the longitude is %{[geoip][location][0]}" 


& t| Bt (condition) 
LogstashAA 1.3.0 版 开始 支持 条 件 判 断 和 表达 式 。 
表达 式 支持 下 面 这 些 操作 符 : 


e == (等 于 )，!= (不 等 于 )，< (小 于 )，> (AT), <= (小 于 等 于 )，>= (大 于 等 
T) 

e =~ (匹配 正则 )，!~ (不 匹配 正则 ) 

e in (& 2), not in (不 包含 ) 

e and (4), or (X), nand(3E 5), xor(3E X) 

。 () (复合 表达 式 )，!() (对 复合 表达 式 结果 取 反 ) 


通常 来 说 ， 你 都 会 在 表达 式 里 用 到 字段 引用 。 为 了 尽量 展示 全 面 各 种 表达 式 ， 下 面 
虚拟 一 个 示例 : 


if "_grokparsefailure" not in [tags] { 


} else if [status] !~ /A2\d\d/ or ( [url] == "/noc.gif" nand [ge 
oip][city] != "beijing" ) { 

} else { 

} 


Logstash 提供 了 一 个 shell 脚本 叫 logstash 方便 快速 运行 。 它 支持 以 下 参数 : 
e -e 


意 即 执行 。 我 们 在 "Hello World" 的 时 候 已 经 用 过 这 个 参数 了 。 pd ae 
任何 具体 配置 ， 直 接 运 行 bin/logstash -e '' 达到 相同 效果 。 这 个 参数 的 默认 
值 是 下 面 这 样 : 


input { 
stdin { } 


j 
output { 
stdout ( } 


e --config 或 -f 
SML. AKBAP > A12 54K K89 BE c HET ARAH shell 所 能 支持 的 
1024 个 字符 长 度 。 所 以 我 们 必 把 配置 固化 到 文件 里 ， 然 后 通过 bin/logstash -f 
agent.conf 这 样 的 形式 来 运行 。 


此 外 ，logstash 还 提供 一 个 方便 我 们 规划 和 书写 配置 的 小 功能 。 你 可 以 直接 用 
bin/logstash -f /etc/logstash.d/ 来 运行 。logstash 会 自动 读 取 
/etc/logstash.d/ 目录 下 所 有 *.conf 的 文本 文件 ， 然 后 在 自己 内 存 里 拼接 
成 一 个 完整 的 大 配置 文件 ， 再 去 执行 。 


VER ， 


logstash 列 出 目录 下 所 有 文件 时 ， 是 字母 排序 的 。 而 logstash 配置 段 的 filter 和 
output 都 是 顺序 执行 ， 所 以 顺序 非常 重要 。 采 用 多 文件 管理 的 用 户 ， 推 荐 采用 数字 
编号 方式 命名 配置 文件 ， 同 时 在 配置 中 ， 严 谨 采 用 if 判断 限定 不 同日 志 的 动 
作 。 


e --configtest 或 -t 


意 即 测试 。 用 来 测试 Logstash 读 取 到 的 配置 文件 语法 是 否 能 正常 解析 。Logstash 
配置 语法 是 用 grammar.treetop 定义 的 。 尤 其 是 使 用 了 上 一 条 提 到 的 读 取 目 录 方 式 
的 读者 ， 尤 其 要 提前 测试 。 


e --log 或 -| 


意 即 日 志 。Logstash 默认 输出 日 志 到 标准 错误 。 生 产 环境 下 你 可 以 通过 
bin/logstash -l logs/logstash.log 命令 来 统一 存储 日 志 。 
e --pipeline-workers 或 -w 

i& fT filter 和 output 的 pipeline 线程 数量 。 默 认 是 CPU 核 数 。 
e --pipeline-batch-size 或 -b 


每 个 Logstash pipeline 线程 ， 在 执行 具体 的 filter 和 output 函数 之 前 ， 最 多 能 累积 
的 日 志 条 数 。 默 认 是 125 条 。 越 大 性 能 越 好 ， 同 样 也 会 消耗 越 多 的 JVM 内 存 。 


e --pipeline-batch-delay 或 -u 


每 个 Logstash pipeline 线程 ， 在 打包 批量 日 志 的 时 候 ， 最 多 等 待 几 毫秒 。 默 认 是 5 
ms ° 


e --pluginpath 或 -P 


可 以 写 自己 的 插件 ， 然 后 用 bin/logstash --pluginpath 
/path/to/own/plugins 加 载 它们 。 


e --verbose 
输出 一 定 的 调试 日 志 。 
e --debug 
输出 更 多 的 调试 日 志 。 


设置 文件 


从 Logstash 5.0 开始 ， 新 增 了 $LS_HOME/config/logstash.yml 文件 ， 可 以 将 
所 有 的 命令 行 参 数 都 通过 YAML 文件 方式 设置 。 同 时 为 了 反映 命令 行 配 置 参 数 的 层 
级 关系 ， 参 数 也 都 改 成 用 .而 不 是 -了 。 


pipeline: 
workers: 24 
batch: 
size: 125 


delay: 5 


plugin 4 3t 


从 logstash 1.5.0 版 本 开始 ，logstash 将 所 有 的 插件 都 独立 拆 分 成 gem EL » 3E > 
每 个 插件 都 可 以 独立 更 新 ， 不 用 等 待 logstash 自身 做 整体 更 新 的 时 候 才 能 使 用 了 


为 了 达到 这 个 目标 ，logstash 配置 了 专门 的 plugins 管理 命令 。 


plugin 用 法 说 明 


Usage: 
bin/logstash-plugin [OPTIONS] SUBCOMMAND [ARG] 


Parameters: 
SUBCOMMAND subcommand 
[ARG] ... subcommand arguments 
Subcommands: 
install Install a plugin 
uninstall Uninstall a plugin 
update Install a plugin 
list List all installed plugins 
Options: 
-h, --help print help 
示例 


首先 ， 你 可 以 通过 bin/logstash-plugin list 查看 本 机 现在 有 多 少 插件 可 
用 。( 其 实 就 在 vendor/bundle/jruby/1.9/gems/ 目录 下 ) 


后 ， 假 如 你 看 到 https://github.com/logstash-plugins/ 下 新 发 布 了 一 个 
logstash-output-webhdfs 模块 (当然 目前 还 没有 )。 打 算 试 试 ， 就 只 需要 运行 : 


bin/logstash-plugin install logstash-output-webhdfs 


就 可 以 了 。 


同样 ， 假 如 是 升级 ， 只 需要 运行 : 


bin/logstash-plugin update logstash-input-tcp 


即 可 。 


本 地 插件 安装 


bin/logstash-plugin 不 单 可 以 通过 rubygems 平台 安装 插件 ， 还 可 以 读 取 本 
地 路 径 的 gem 文件 。 这 对 自 定 义 插 件 或 者 无 外 接 网 络 的 环境 都 非常 有 效 : 


bin/logstash-plugin install /path/to/logstash-filter-crash.gem 


执行 成 功 以 后 。 你 会 发 现 ，logstash-5.0.0 目录 下 的 Gemfile 文件 最 后 会 多 出 一 段 
内 容 : 


gem "logstash-filter-crash", "1.1.0", :path => "vendor/local_gem 
s/d354312c/logstash- filter -mweibocrash-1.1.0" 


同时 Gemfile jruby-1.9.lock 文件 开头 也 会 多 出 一 段 内 容 : 


PATH 
remote: vendor/local_gems/d354312c/logstash-filter-crash-1.1.0 
specs: 
logstash-filter-crash (1.1.0) 
logstash-core (>= 1.4.0, < 2.0.0) 


长 期 运行 


完成 上 一 节 的 初次 运行 后 ， 你 肯定 会 发 现 一 点 : 一 旦 你 按 下 , HIPS ER 
输出 ，logstash 进程 也 就 随 之 停止 了 。 作 为 一 个 肯定 要 长 期 运行 的 程序 ， 应 该 怎么 
处 理 呢 ? 


本 章节 问题 对 于 一 个 运 维 来 说 应 该 属于 基础 知识 ， 鉴 于 ELK 用 户 很 多 其 实 不 是 运 
维 ， 添 加 这 段 内 容 。 


办 法 有 很 多 种 ， 下 面 介 绍 四 种 最 常用 的 办 法 : 


标准 的 Service 方式 


采用 RPM ^ DEB 发 行 包 安 装 的 读者 ， 推 荐 采用 这 种 方式 。 发 行 包 内 ， 都 自 带 有 
sysV 或 者 systemd 风格 的 启动 程序 /配置 ， 你 只 需要 直接 使 用 即 可 。 


以 RPM 为 例 ，/etc/init.d/logstash 脚本 中 ， 会 加 载 
/etc/init.d/functions 库 文 件 ， 利 用 其 中 的 daemon Až > Xt logstash 3t 
程 作为 后 台 程 序 运行 。 


所 以 ， 你 只 需 把 自己 写 好 的 配置 文件 ， 统 一 放 在 /etc/logstash/conf.d 目录 下 
(注意 目录 下 所 有 配置 文件 都 应 该 是 .conf 结尾 ， 且 不 能 有 其 他 文本 文件 存在 。 因 为 
logstash agent 启动 的 时 候 是 读 取 全 文件 夹 的 )， 然 后 运行 service logstash 
start PART ° 


& X Ah 49 nohup 方式 


文 是 最 简单 的 方式 ， 也 是 linux 新 手 们 很 容易 搞 混淆 的 一 个 经 典 问题 : 


command 
/dev/null 
/dev/null 2>&1 


command 
command 


/dev/null & 
command /dev/null 2»&1 & 
command &> /dev/null 

nohup command &» /dev/null 


> 
> 
command & 
command > 
> 


请 回答 以 上 命令 的 异同 ..…… 
具体 不 一 一 解释 了 。 直接 说 答案 ， 想 要 维持 一 个 长 期 后 台 运 行 的 logstash， 你 需要 
同时 在 命令 前 面 加 nohup ， 后 面 加 & » 


更 优雅 的 SCREEN 方式 


screen 算是 linux 运 维 一 个 中 高 级 技巧 。 通 过 screen 命令 创建 的 环境 下 运行 的 终 
端 命令 ， 其 父 进 程 不 是 sshd 登录 会 话 ， 而 是 screen 。 这 样 就 可 以 即 避 免 用 户 退 出 
进程 消失 的 问题 ， 又 随时 能 重新 接管 回 终端 继续 操作 。 


创建 独立 的 screen 命令 如 下 : 
screen -dmS elkscreen_1 
接管 连 入 创建 的 elkscreen 1 命令 如 下 : 


Screen -r elkscreen 1 


然后 你 可 以 看 到 一 个 一 模 一 样 的 终端 ， 运行 logstash 之 后 ， 不 要 按 CtrlI+C， 而 是 
按 Ctrl+A+D 键 ， 断 开 环境 。 想 重新 接管 ， 依 然 screen -r elkscreen 1 FP 


如 果 创 建 了 多 个 screen， 查 看 列表 命令 如 下 : 


screen -list 


最 推荐 的 daemontools 方式 


不 管 是 nohup 还 是 Screen， 都 不 是 可 以 很 方便 管理 的 方式 ， 在 运 维 管理 一 个 ELK 
集群 的 时 候 ， 必 须 寻 找 一 种 尽 可 能 简洁 的 办 法 。 所 以 ， 对 于 需要 长 期 后 台 运 行 的 大 


EF o ' 如 果 就 一 个 进程 ， 还 是 学 习 一 下 怎么 写 init 脚本 吧 )， 推 荐 大 家 
使 用 一 款 daemontools 工具 。 


daemontools 是 一 个 软件 名 称 ， 不 过 配置 略 复杂 。 所 以 这 里 我 其 实 是 用 其 名 称 来 指 
代 整 个 同类 产品 ， 包 括 但 不 限于 python 实现 的 supervisord > perl 实现 的 ubic， 
ruby 实现 的 god 等 。 


以 supervisord 为 例 ， 因 为 这 个 出 来 的 比较 早 ， 可 以 直接 通过 EPEL 仓库 安装 。 


yum -y install supervisord --enablerepo=epel 


在 /etc/supervisord.conf 配置 文件 里 添加 内 容 ， 定 义 你 要 启动 的 程序 : 


[program:elkpro. 1] 

environment-LS HEAP SIZE-5000m 

directory-/opt/logstash 

command-/opt/logstash/bin/logstash -f /etc/logstash/proi.conf -w 
10 -1 /var/log/logstash/proi.log 

[program:elkpro 2] 

environment-LS HEAP SIZE-5000m 

directory=/opt/logstash 

command=/opt/logstash/bin/logstash -f /etc/logstash/pro2.conf -w 
10 -1 /var/log/logstash/pro2.log 


然后 启动 service supervisord start PPT ° 


logstash 会 以 子 进程 的 身份 运行 ， 你 还 可 以 使 用 supervisorctl 命 
不 一 


令 ， 单 独 控制 一 系列 logstash 子 进程 中 某 一 个 进程 的 启 停 操 作 : 


supervisorctl stop elkpro_2 


输入 插件 (Input) 


在 "Hello World" 示例 中 ， 我 们 已 经 见 到 并 介绍 了 logstash 的 运行 流程 和 配置 的 基 

础 语法 。 从 这 章 开 始 ， 我 们 就 要 逐一 介绍 logstash 流程 中 比较 常用 的 一 些 插 件 ， 并 
在 介绍 中 针对 其 主要 适用 的 场景 ， 推 荐 的 配置 ， 作 一 些 说 明 。 

限于 篇 幅 ， 接 下 来 内 容 中 ， 配 置 示例 不 一 定 能 贴 完整 。 请 记 住 一 个 原则 : Logstash 
配置 一 定 要 有 一 个 input 和 一 个 output。 在 演示 过 程 中 ， 如 果 没 有 写 明 input? RU 
就 会 使 用 "hello world" 里 我 们 已 经 演示 过 的 input/stdin ， 同 理 ， 没 有 写 明 的 output 


就 是 output/stdout 。 


以 上 请 读者 自明 。 


cL ` m" 

读 取 文件 (File) 

分 析 网 站 访问 日 志 应 该 是 一 个 运 维 工程 师 最 常见 的 工作 了 。 所 以 我 们 先 学 习 一 下 怎 
么 用 logstash 来 处 理 日 志文 件 。 


Logstash 使 用 一 个 名 叫 FileWatch 的 Ruby Gem 库 来 监听 文件 变化 。 这 个 库 支 持 
glob 展开 文件 路 径 ， 而 且 会 记录 一 个 叫 .sincedb 的 数据 库 文 件 来 跟踪 被 监听 的 日 
志文 件 的 当前 读 取 位 置 。 所 以 ， 不 要 担心 logstash 会 漏 过 你 的 数据 。 


sincedb 文件 中 记录 了 每 个 被 监听 的 文件 的 inode, major number, minor number 和 
pos ° 


配置 示例 


input { 
file { 
path => ["/var/log/*.log", "/var/log/message" | 
type => "system" 
start_position => "beginning" 


有 一 些 比 较 有 用 的 配置 项 ， 可 以 用 来 指定 FileWatch 库 的 行为 : 
e discover_interval 


logstash 每 隔 多 久 去 检查 一 次 被 监听 的 path 下 是 否 有 新 文件 。 上 默认 值 是 15 


秒 。 
e exclude 
不 想 被 监听 的 文件 可 以 排除 出 去 ， 这 里 跟 path 一 样 支持 glob 展开 。 


e close_older 


一 个 已 经 监听 中 的 文件 ， 如 果 超 过 这 个 值 的 时 间 内 没有 更 新 内 容 ， 就 关闭 监听 它 的 
文件 句柄 。 默 认 是 3600 秒 ， 即 一 小 时 。 


e ignore_older 


在 每 次 检查 文件 列表 的 时 候 ， 如 果 一 个 文件 的 最 后 修改 时 间 超过 这 个 值 ， 就 忽略 这 
个 文件 。 默 认 是 86400 秒 ， 即 一 天 。 


e sincedb path 


如 果 你 不 想 用 默认 的 $HOME/.sincedb (Windows 平台 上 在 
C:\Windows\System32\config\systemprofile\,.,sincedb )， 可 以 通过 这 个 配 
置 定 义 Sincedb 文件 到 其 他 位 置 。 


e sincedb_write_interval 

logstash 每 隔 多 久 写 一 次 sincedb x fF > RU Æ 15 FF » 
e stat interval 

logstash 每 隔 多 久 检 查 一 次 被 监听 文件 状态 (是 否 有 更 新 ) ， 默 认 是 1 秒 。 
e start_position 


logstash 从 什么 位 置 开始 读 取 文件 数据 ， 默 认 是 结束 位 置 ， 也 就 是 说 logstash 进程 
会 以 类 似 tail -F 的 形式 运行 。 如 果 你 是 要 导入 原 有 数据 ， 把 这 个 设 定 改 成 
"beginning" > logstash 进程 就 从 头 开 始 读 取 ， 类 似 less +F 的 形式 运行 。 


1. 通常 你 要 导入 原 有 数据 进 Elasticsearch 的 话 ， 你 还 需要 filter/date 插件 来 修改 
默认 的 "@timestamp" 字段 值 。 稍 后 会 学 习 这 方面 的 知识 。 

2. FileWatch 只 支持 文件 的 绝对 路 径 ， 而 且 会 不 自动 递归 目录 。 所 以 有 需要 的 
话 ， 请 用 数组 方式 都 写 明 具 体 哪些 文件 。 

3. LogStash::Inputs::File 只 是 在 进程 运行 的 注册 阶段 初始 化 一 个 FileWatch 对 
象 。 所 以 它 不 能 支持 类 似 fluentd 那样 的 path => "/path/to/% 
{+yyyy/MM/dd/hh}.log" 写法 。 达 到 相同 目的 ， 你 只 能 写成 path => 
"/path/to/*/*/*/*.log" ° FileWatch 模块 提供 了 一 个 稍微 简单 一 点 的 写 
法 : /path/to/**/*.log ， 用 ** 来 缩写 表示 递归 全 部 子 目 录 。 

4. 在 单个 input/file 中 监听 的 文件 数量 太 多 的 话 ， 每 次 启动 扫描 构建 监听 队列 会 消 


耗 较 多 的 时 间 。 给 使 用 者 的 感觉 好 像 读 取 不 到 一 样 ， 这 是 正常 现象 。 

start position 仅 在 该 文件 从 未 被 监听 过 的 时 候 起 作用 。 如 果 sincedb x: 
件 中 已 经 有 这 个 文件 的 inode 记录 了 ， 那 么 logstash 依然 会 从 记录 过 的 pos 
开始 读 取 数 据 。 所 以 重复 测试 的 时 候 每 回 需要 删除 sincedb 文件 (官方 博客 上 提 
供 了 另 一 个 巧妙 的 思路 :将 sincedb_path 定义 为 /dev/null ， 则 每 次 重 
启 自动 从 头 开始 读 ) 。 
. AA windows 平台 上 没有 inode 的 概念 ，Logstash 某 些 版 本 在 windows 平台 
上 监听 文件 不 是 很 靠 谱 。windows 平台 上 ， 推 荐 考虑 使 用 nxlog 作为 收集 端 ， 
参阅 本 书 稍 后 章节 。 


标准 输入 (Stdin) 


我 们 已 经 见 过 好 几 个 示例 使 用 stdin 了 。 这 也 应 该 是 logstash 里 最 简单 和 基础 
的 插件 了 。 


所 以 ， 在 这 段 中 ， 我 们 可 以 学 到 一 些 未 来 每 个 插件 都 会 有 的 一 些 方法 。 
配置 示例 


input { 
stdin { 
add_field => {"key" => "value"} 
codec => "plain" 
tags => ["add"] 
type => "std" 


Ww 


用 上 面 的 新 stdin 设置 重新 运行 一 次 最 开始 的 hello world 示例 。 我 建议 大 家 把 
整 段 配置 都 写 入 一 个 文本 文件 ， 然 后 运行 命令 : bin/logstash -f 
stdin.conf ° 4A "hello world" 并 回 车 后 ， 你 会 在 终端 看 到 如 下 输出 : 


"message" => 


"@version" => 
"@timestamp" => 
"type" => 
"tags" => 
[0] "add" 

], 
"key" => 
"host" => 


解释 


type 和 tags 是 logstash 事件 中 两 个 特殊 的 字段 。 
过 type 来 标记 事件 类 型 一 一 我 们 肯定 是 
tags 则 是 在 数据 处 理 过 程 中 ， 


"hello world", 

"q", 
"2014-08-08T06:48:47.789Z", 
‘Sede; 

[ 


"value", 
"raochenlindeMacBook-Air.local" 


ee ae 
a 于 什么 类 型 的 。 而 
由 具体 的 插件 来 添加 或 者 删除 的 。 


常见 的 用 法 是 像 下 面 这 样 : 


input { 
stdin { 
type => "web" 


j 
j 
filter 1 
if [type] == "web" { 
grok ( 
match => ["message", %{COMBINEDAPACHELOG} ] 
j 
j 
j 
output { 
if " grokparsefailure" in [tags] { 
nagios nsca { 
nagios status -» "1" 
j 
} else { 
elasticsearch { 
j 
j 
j 


看 起 来 蛮 复 杂 的 ， 对 吧 ? 


继续 学 习 ， 你 也 可 以 写 出 来 的 。 


T£ FL Syslog 数据 


syslog 可 能 是 运 维 领域 最 流行 的 数据 传输 协议 了 。 当 你 想 从 设备 上 收集 系统 日 志 的 
ITAR > syslog 应 该 会 是 你 的 第 一 选择 。 尤 其 是 网 络 设备 ， 比 如 思科 —— syslog JL 
乎 是 唯一 可 行 的 办 法 。 


我 们 这 里 不 解释 如 何 配 置 你 的 syslog.conf , rsyslog.conf 或 者 syslog- 
ng.conf 来 发 送 数 据 ， 而 只 讲 如 何 把 logstash 配置 成 一 个 syslog 服务 器 来 接收 数 
据 。 


有 关 rsyslog 的 用 法 ， 稍 后 的 类 型 项 目 一 节 中 ， 会 有 更 详细 的 介绍 。 
配置 示例 


input { 


syslog { 
port => "514" 


} 
} 


运行 结果 


作为 最 简单 的 测试 ， 我 们 先 暂 停 一 下 本 机 的 syslogd (或 rsyslogd ) 进 程 ， 然 
后 启动 logstash 进程 (这样 就 不 会 有 端口 冲突 问题 )。 现 在 ， 本 机 的 syslog 就 会 
默认 发 送 到 logstash 里 了 。 我 们 可 以 用 自 带 的 logger 命令 行 工具 发 送 一 条 
"Hello World" 信 息 到 syslog 里 ( 即 logstash €) 。 看 到 的 logstash 输出 像 下 面 这 
样 : 


"message" 
"@version" 
"@timestamp" 
NOSE. 
DESIRES 
"timestamp" 
"logsource" 
"program" 

"pid" 

"severity" 
PACIL 
"facility label" 
"severity_label" 


"Hello World", 

"4", 

"2014-08-08T09:01:15.911Z", 
Laird es oes ae 

31, 

AUC OB 73041715 
"raochenlindeMacBook-Air.local", 
"com.apple.metadata.mdflagwriter", 
agg 

7, 

3, 

"system", 

"Debug" 


Logstash 是 用 UDPSocket , TCPServer 和 LogStash::Filters::Grok 来 实 
3L LogStash::Inputs::Syslog 的 。 所 以 你 其 实 可 以 直接 用 logstash 配置 实现 


一 样 的 效果 : 


input { 


tcp { 
port => "8514" 


} 
filter { 


grok { 


match => ["message", 


} 
syslog_pri { } 


Jk dE È BK 


"9%£SYSLOGLINE}" ] 


建议 在 使 用 LogStash::Inputs::Syslog 的 时 候 走 TCP 协议 来 传输 数据 。 


因为 具体 实现 中 ，UDP 监听 器 只 用 了 一 个 线程 ， 而 TCP 监听 器 会 在 接收 每 个 连接 
的 时 候 都 启动 新 的 线程 来 处 理 后 续 步 又 。 


如 果 你 已 经 在 使 用 UDP 监听 器 收集 日 志 ， 用 下 行 命 令 检查 你 的 UDP 接收 队列 大 
小 : 


# netstat -plnu | awk 'NR==1 || $4~/:514$/{print $2}' 
Recv-Q 
228096 


228096 是 UDP 接收 队列 的 默认 最 大 大 小 ， 这 时 候 linux 内 核 开始 丢弃 数据 包 了 


强烈 建议 使 用 Logstash::Inputs::TCP 和 LogStash::Filters::Grok 配合 实 
现 同样 的 syslog 功能 ! 


虽然 LogStash::Inputs::Syslog 在 使 用 TCPServer 的 时 候 可 以 采用 多 线程 处 理 数据 
的 接收 ， 但 是 在 同一 个 客户 端 数据 的 处 理 中 ， 其 grok fe date 是 一 直 在 该 线程 中 完 
成 的 ， 这 会 导致 总 体 上 的 处 理性 能 几何 级 的 下 降 经 过 测试 ，TCPServer 每 秒 
可 以 接收 50000 条 数据 ， n 同一 线程 中 启用 grok 后 每 秒 只 能 处 理 5000 条 ， 再 
加 上 date 只 能 达到 500 条 





才 将 这 两 步 拆 分 到 filters 阶段 后 ，logstash 支持 对 该 阶段 插件 单独 设置 多 线程 运 
行 ， 大 大 提高 了 总 体 处 理性 能 。 在 相同 环境 下 ， logstash -f tcp.conf -w 20 
的 测试 中 ， 总 体 处 理性 能 可 以 达到 每 秒 30000 条 数据 ! 


: 测试 采用 logstash 作者 提供 的 yes "<44>May 19 18:30:17 snack jls: 
foo bar 32" | nc localhost 3000 命令 。 出 处 
见 : https://github.com/jordansissel/experiments/blob/master/ruby/jruby- 
netty/syslog-server/Makefile 


小 贴 士 


如 果 你 实在 没 法 切换 到 TCP 协议 ， 你 可 以 自己 写 程序 ， 或 者 使 用 其 他 基于 异步 1O 
匡 架 (比如 libev ) 的 项 目 。 下 面 是 一 个 简单 的 异步 IO 实现 UDP 监听 数据 输入 
Elasticsearch 的 示例 : 


https://gist.github.com/chenryn/7c922ac424324ee0d695 


input & & 


40 


读 取 网 络 数据 (TCP) 


未 来 你 可 能 会 用 Redis 服务 器 或 者 其 他 的 消息 队列 系统 来 作为 logstash broker 的 
角色 。 不 过 Logstash 其 实 也 有 自己 的 TCP/UDP 插件 ， 在 临时 任务 的 时 候 ， 也 算 
能 用 ， 尤 其 是 测试 环境 。 


小 贴 士 : 虽然 Logstash::Inputs::TCP 用 Ruby 的 Socket 和 OpenSSL JE 
实现 了 高 级 的 SSL 功能 ， 但 Logstash 本 身 只 能 在 SizedQueue 中 缓存 20 ^F 
件 。 这 就 是 我 们 建议 在 生产 环境 中 换 用 其 他 消息 队列 的 原因 。 


配置 示例 


input { 
tcp { 
port => 8888 
mode => "server" 
ssl_enable => false 


Ww 


第 见 场景 


目前 来 看 ， LogStash::Inputs::TCP 最 常见 的 
据 。 在 启动 logstash 进程 后 ， 在 另 一 个 终端 运行 


用 法 就 是 配合 nc 命令 导入 旧 数 
如 下 命令 即 可 导入 数据 : 


# nc 127.0.0.1 8888 < olddata 


这 种 做 法 比 用 LogStash::Inputs::File 43$» AX% nc 命令 结束 ， 我 们 就 知道 


数据 导入 完毕 了 。 而 用 input/file 方式 ，logstash 进程 还 会 一 直 等 待 新 数据 输入 被 监 


听 的 文件 ， 不 能 直接 看 出 是 否 任务 完成 了 。 


编码 插件 (Codec) 


Codec X logstash 从 1.3.0 版 开始 新 引入 的 概念 (Codec 来 自 Coder/decoder 两 个 
单词 的 首 字母 缩写 )。 


在 此 之 前 ，logstash 只 支持 纯 文本 形式 输入 ， 然 后 以 过 滤器 处 理 它 。 但 现在 ， 我 们 
可 以 在 输入 期 处 理 不 同类 型 的 数据 ， 这 全 是 因为 有 了 codec 设置 。 


所 以 ， 这 里 需要 纠正 之 前 的 一 个 概念 。Logstash 不 只 是 一 个 input | filter | 
output 的 数据 流 ， 而 是 一 个 input | decode | filter | encode | output 
的 数据 流 ! codec 就 是 用 来 decode ` encode 事件 的 。 


codec 的 引入 ， 使 得 logstash 可 以 更 好 更 方便 的 与 其 他 有 自 定 义 数据 格式 的 运 维 产 
品 共存 ， 比 如 graphite、fluent、netflow、collectd， 以 及 使 用 msgpack、json、 
edn 等 通用 数据 格式 的 其 他 产品 等 。 


事实 上 ， 我 们 在 第 一 个 "hello world" 用 例 中 就 已 经 用 过 codec 了 一 rubydebug 
就 是 一 种 codec! 虽然 它 一 般 只 会 用 在 stdout 插件 中 ， 作 为 配置 测试 或 者 调试 的 工 
具 。 


小 贴 士 : 这 个 五 段 式 的 流程 说 明 源 自 Perl 版 的 Logstash (后 来 改名 叫 
Message::Passing 模块 ) 的 设计 。 本 书 最 后 会 对 该 模块 稍 作 介绍 。 


采用 JSON 编码 


在 早期 的 版 本 中 ， 有 一 种 降低 logstash 过 滤器 的 CPU 负载 消耗 的 做 法 盛行 于 社区 
(在 当时 的 cookbook 上 有 专门 的 一 节 介 绍 ) : 直接 输入 预定 义 好 的 ISON 数据 ， 这 
样 就 可 以 省 略 掉 filtergrok 配置 ! 


这 个 建议 依然 有 效 ， 不 过 在 当前 版 本 中 需要 稍微 做 一 点 配置 变动 
专门 的 codec 设置 。 





因为 现在 有 


配置 示例 


社区 常见 的 示例 都 是 用 的 Apache 的 customlog。 不 过 我 觉得 Nginx 是 一 个 比 
Apache 更 常用 的 新 型 web 服务 器 ， 所 以 我 这 里 会 用 nginx.conf 做 示例 : 


logformat json '{"@timestamp":"$time_iso8601", ' 
'"Qversion":"1",' 
'""host":"$server addr", ' 
'client":"$remote_addr", ' 
'"size":$body_bytes_sent, ' 
'""responsetime":$request time, ' 
'"domain":"$host", ' 
SAU gd Baek Tone 
'"status":"$status"}'; 

access_log /var/log/nginx/access.log_json json; 


注意 :在 $request time 和 $body_bytes_sent 变量 两 头 没有 双 引 号 "> 
这 两 个 数据 在 ISON 里 应 该 是 数值 类 型 | 


重启 nginx 应 用 ， 然 后 修改 你 的 input/file 区 段 配置 成 下 面 这 样 : 


input { 
file { 
path => "/var/log/nginx/access.log_json" 
codec => "json" 


下 面 访问 一 下 你 nginx 发 布 的 web 页面， 然后 你 会 看 到 logstash 进程 输出 类 似 下 
面 这 样 的 内 容 : 


{ 
"@timestamp" => "2014-03-21T18:52:25.000+08:00", 
"@version" => "1", 
"host" => "raochenlindeMacBook-Air.local", 
Clent =. "12039 125 /TASS 
"size" -» 8096, 
"responsetime" => 0.04, 
"domain" => "www.domain.com", 
"url" => "/path/to/file.suffix", 
"status" => "200" 
y 


小 贴 士 


对 于 一 个 web 服务 器 的 访问 日 志 ， 看 起 来 已 经 可 以 很 好 的 工作 了 。 不 过 如 果 Nginx 
pe ， 访问 日 志 里 有 些 变量 ， 比 如 说 

$upstream response time ， 可 能 不 会 一 直 是 数字 ， 它 也 可 能 是 一 个 "-" F 
符 串 ! 这 会 直接 导致 logstash 对 输入 数据 验证 报 弄 常 


有 两 个 办 法 解决 这 个 问题 : 
1. 用 sed 在 输入 之 前 先 替换 - 成 9。 
运行 logstash 进程 时 不 再 读 取 文 件 而 是 标准 输入 ， 这 样 命令 就 成 了 下 面 这 个 样子 : 
tail -F /var/log/nginx/proxy_access.log_json \ 
| sed 's/upstreamtime":-/upstreamtime":0/' \ 


| /usr/local/logstash/bin/logstash -f /usr/local/logstash/et 
c/proxylog.conf 


1. 日 志 格 式 中 统一 记录 为 字符 串 格 式 ( 即 都 带 上 双 引 号 " )， 然 后 再 在 logstash 
中 用 filter/mutate 插件 来 变更 应 该 是 数值 类 型 的 字符 字段 的 值 类 型 。 


A X€ LogStash::Filters::Mutate 的 内 容 ， 本 书 稍 后 会 有 介绍 。 


合并 多 行 数据 (Multiline) 


有 些 时 候 ， 应 用 程序 调试 日 志 会 包含 非常 丰富 的 内 容 ， 为 一 个 事件 打印 出 很 多 行 
容 。 这 种 日 志 通 常 都 很 难 通过 命令 行 解析 的 方式 做 分 析 。 


而 logstash 正 为 此 准备 好 了 codec/multiline 插件 ! 


小 贴 士 : multiline 插件 也 可 以 用 于 其 他 类 似 的 堆栈 式 信息 ， 比 如 linux 的 内 核 日 


Eo 


A 


配置 示例 


input { 
stdin { 
codec => multiline { 
pattern => "A\[" 
negate => true 
what => "previous" 


WwW 


运行 logstash 进程 ， 然 后 在 等 待 输入 的 终端 中 输入 如 下 几 行 数据 : 


[Aug/08/08 14:54:03] hello world 
[Aug/08/09 14:54:04] hello logstash 
hello best practice 
hello raochenlin 
[Aug/08/10 14:54:05] the end 


你 会 发 现 logstash 输出 下 面 这 样 的 返回 : 


"@timestamp" => "2014-08-09T13:32:03.368Z", 
"message" => "[Aug/08/08 14:54:03] hello world\n", 
POVeLDSTONU cU 
"host" => "raochenlindeMacBook-Air.local" 
} 
{ 
"@timestamp" => "2014-08-09T13:32:24.359Z', 
"message" => "[Aug/08/09 14:54:04] hello logstash\n\n 
hello best practice\n\n hello raochenlin\n", 
YOversione > 
"tags" => [ 
[0] "multiline" 
], 
"host" => "raochenlindeMacBook-Air.local" 
} 
你 看 ， 这 个 事件 ， 在 "message" 字段 里 存储 了 三 行 数据 | 
小 贴 士 : 你 可 能 注意 到 输出 的 事件 中 都 没有 最 后 的 "fhe end" 字 符 串 。 


后 输入 的 回 车 符 \n 并 不 匹配 4 E ^N 正则 表达 Ha Cu 


数据 直到 匹配 成 功 后 才 会 输出 这 个 事件 。 


解释 


其 实 这 个 插件 的 原理 很 简单 ， 就 是 把 当前 行 的 数据 添加 到 前 面 一 行 后 面 ，， 直 到 新 


进 的 当前 行 匹配 ^N[ 正则 为 止 。 


这 个 正则 还 可 以 用 grok 表达 式 ， 稍 后 你 就 会 学 习 这 方面 的 内 容 。 


Log4J 的 另 一 种 


说 到 应 用 程序 日 志 ，log4j # 


也 确实 是 一 个 办 法 S 


` 


ms 
TR 


第 


一 个 被 大 家 想到 的 。 使 用 codec/multiline 


不 过 ， 如 果 你 本 身 就 是 开发 人 员 ， 或 者 可 以 推动 程序 修改 变更 的 话 ，logstash 还 提 
供 了 另 一 种 处 理 log4j 的 方式 input/log4j° 4 codec/multiline 不 同 ， 这 个 插 
件 是 直接 调用 了 org.apache.log4j.spi.LoggingEvent 处 理 TCP 端口 接收 的 
数据 。 稍 后 章节 会 详细 讲述 log4j 的 用 法 。 


推荐 阅读 


https://github.com/logstash-plugins/logstash-patterns- 
core/blob/master/patterns/java 


collectd ij i 


本 节 作 者 : crazw 


collectd 是 一 个 守护 (daemon) 进 程 ， 用 来 收集 系统 性 能 和 提供 各 种 存储 方式 来 存储 
不 同 值 的 机 制 。 它 会 在 系统 运行 和 存储 信息 时 周期 性 的 统计 系统 的 相关 统计 信息 。 
利用 这 些 信 息 有 助 于 查找 当前 系统 性 能 瓶颈 (如 作为 性 能 分 析 performance 
analysis ) 和 预测 系统 未 来 的 load (如 能 力 部 署 capacity planning ) 等 


下 面 简单 介绍 一 下 : collectd 的 部 署 以 及 与 logstash 对 接 的 相关 配置 实例 
collectd 的 安装 


软件 仓库 安装 (推荐 ) 


collectd 官 方 有 一 个 的 软件 仓库 : https://pkg.ci.collectd.org ， 构 建 
有 RHEL/CentOS (rpm)* Debian/Ubuntu (deb) 的 软件 包 ， 如 果 你 使 用 的 操作 系 
统 属 于 上 述 ， 那 么 推荐 使 用 软件 仓库 安装 。 


目前 collectd 官 方 维护 3 个 版 本 : 5.4, 5.5, 5.6 。 根 据 需 要 选择 合适 的 版 本 。 


Debian/Ubuntu 仓 库 安 装 (示例 中 使 用 5.5 版 本 ): 


echo "deb http://pkg.ci.collectd.org/deb $(lsb release -sc) coll 
ectd-5.5" | sudo tee /etc/apt/sources.list.d/collectd.list 

curl -s https://pkg.ci.collectd.org/pubkey.asc | sudo apt-key ad 
d - 

sudo apt-get update && sudo apt-get install -y collectd 


NOTE: Debian/Ubuntu 软 件 仓库 自 带 有 collectd 软件 包 ， 如 果 软 件 仓库 自 带 
的 版 本 足够 你 使 用 ， 那 么 可 以 不 用 添加 人 仓库， 直接 通过 apt-get install 
collectd PPT ° 


RHEL/CentOS 仓 库 安装 (示例 中 使 用 5.5 版 本 ): 


cat > /etc/yum.repos.d/collectd.repo ««EOF 

[collectd-5.5] 

name=collectd-5.5 
baseurl=http://pkg.ci.collectd.org/rpm/collectd-5.5/epel-\$relea 
sever -\$basearch/ 

gpgcheck=1 

gpgkey=http://pkg.ci.collectd.org/pubkey.asc 

EOF 


yum install -y collectd 


bl 


+ Ay 7 ^ l4- bl de db eet wt So, TEST Lh. 4 ] 
# 其 他 col]lectd 插 件 需要 安装 对 应 的 collectd-xxxx 软 件 包 


源码 安装 collectd 


4 COllectd 目 前 维护 3 个 版 本 ，5.4，5.5，5.6。 根 据 自 己 需 要 选择 版 本 

wget http://collectd.org/files/collectd-5.4.1.tar.gz 

tar zxvf collectd-5.4.1.tar.gz 

cd collectd-5.4.1 

./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var 
--libdir=/usr/lib --mandir=/usr/share/man --enable-all-plugins 


make && make install 


解决 依赖 (RH 系列 ): 


rpm -ivh "http://dl.fedoraproject.org/pub/epel/6/i386/epel-relea 
se-6-8.noarch.rpm" 

yum -y install libcurl libcurl-devel rrdtool rrdtool-devel perl- 
rrdtool rrdtool-perl libgcrypt-devel gcc make gcc-c++ liboping 1 
iboping-devel perl-CPAN net-snmp net-snmp-devel 


安装 启动 脚本 


cp contrib/redhat/init.d-collectd /etc/init.d/collectd 
chmod +x /etc/init.d/collectd 


A i collectd 


service collectd start 


collectd 的 配置 


以 下 配置 可 以 实现 对 服务 器 基本 的 CPU、 内 存 、 网 卡 流量 、 磁 盘 O 以 及 磁盘 空间 
占用 情况 的 监控 : 


Hostname "host.example.com" 

LoadPlugin interface 

LoadPlugin cpu 

LoadPlugin memory 

LoadPlugin network 

LoadPlugin df 

LoadPlugin disk 

<Plugin interface> 
Interface "etho" 
IgnoreSelected false 

</Plugin> 

<Plugin network> 
# logstash 的 IP 地 址 和 collectd 的 数据 接收 端口 号 > 
# 如 果 1ogstash 和 collectd 在 同一 台 主 机 上 也 可 以 用 环 回 地 址 127.0.0.1 
<Server "10.0.0.1" "25826"> 
</Server> 

</Plugin> 


logstash $^ & & 


以 下 配置 实现 通过 logstash 监听 25826 端口 ， 接 收 从 collectd 发 送 过 来 的 各 项 
会 测 数 据 o 


logstash 上 默认 自 带 有 collectd 的 codec 插 件 ， 详 见 官方 文档 : 
https://www.elastic.co/guide/en/logstash/current/plugins-codecs-collectd.html 


示例 : 


input { 
udp { 
port => 25826 
buffer_size => 1452 
workers => 3 # Default is 2 
queue_size => 30000 # Default is 2000 
codec => collectd { } 
type => "collectd" 


下 面 是 简单 的 一 个 输出 结果 : 


codec & a. 


{ 
" index": "logstash-2014.12.11", 
"Evpe c "collectd ^ 
" id": "dS6vVz4aRtK5xS86kwjZnw" , 
"score": null, 
"_ source": { 
"host": "host.example.com", 
"Qtimestamp": "2014-12-11T06:28:52.118Z", 
"plugin": “interface”, 
"plugin instance": "etho", 
"collectd type": "if packets" 
MIX TOGTAT AAA 
"Ex 1096086297 
COVENS TOMA: qu 
"type": "collectd", 
"tags Il 
" grokparsefailure" 
] 
3 
“SOMe el 
1418279332118 
] 
} 


e collectd 支 持 收集 的 数据 类 型 : http://git.verplant.org/? 
p=collectd.git;a=blob;hb=master;f=README 


e collectd 收 集 各 数据 类 型 的 配置 参考 资料 : 
http://collectd.org/documentation/manpages/collectd.conf.5.shtml 


e collectd 简 单 配置 文件 示例 : 
https://gist.github.com/untergeek/ab85cb86a9bf39f1fc6d 
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netflow 


input { 
udp { 
port => 9995 
codec => netflow { 
definitions => "/home/administrator/logstash-1.4.2/1lib/l 
ogstash/codecs/netflow/net flow. yaml" 
versions => [5] 


output { 
stdout { codec => rubydebug } 
if ( [host] =~ "10\.1\.1[12]\.1" ) { 
elasticsearch { 
index => "logstash_netflow5-%{+YYYY.MM.dd}" 
host => "localhost" 
} 
} else { 
elasticsearch { 
index => "logstash-%{+YYYY.MM.dd}" 
host => "localhost" 


curl -XPUT localhost:9200/ template/logstash netflow5 -d '{ 


"template" : "logstash netflow5-*", 
"settings": { 
"index.refresh_interval": "5s" 
3 
"mappings" : ( 
" default " : { 


" all" : ("enabled" : false}, 


"properties" : ( 
"Qversion": ( "index": "analyzed", "type": "integer" } 


"@timestamp": { "index": "analyzed", "type": "date" }, 
"netflow": { 

"dynamic": true, 

"type": "object", 

"properties": { 


"version": { "index": "analyzed", "type": "integer 
n 

"flow seq num": ( "index": "not analyzed", "type": 

"long" }, 

"engine type": ( "index": "not analyzed", "type": 
"integer" }, 

"engine id": ( "index": "not analyzed", "type": "i 
nteger" }, 

"sampling algorithm": ( "index": "not analyzed", " 
type": "integer" }, 

"sampling interval": { "index": "not analyzed", "t 
ype": "integer" }, 

"flow records": { "index": "not analyzed", "type": 

"integer" }, 

"ipv4 src addr": ( "index": "analyzed", "type": "i 
p" j, 

"ipv4 dst addr": ( "index": "analyzed", "type": "i 
p" }, 

"ipv4 next hop": ( "index": "analyzed", "type": "i 
p" j, 

"input snmp": { "index": "not analyzed", "type": " 
long" }, 

"output snmp": ( "index": "not analyzed", "type": 
"long" }, 

"in pkts": { "index": "analyzed", "type": "long" } 

"in bytes": ( "index": "analyzed", "type": "long" 
ty 

"first switched": { "index": "not analyzed", "type 
vs "date" y, 

"last_switched": { "index": "not_analyzed", "type" 


"date" $r 


"l4 src port": { "index": "analyzed", "type": "lon 


"i4 dst port": { "index": "analyzed! "type": "lon 


"tcp flags": { "index": "analyzed", "type": "integ 


"protocol": { "index": "analyzed", "type": "intege 
"src tos": { "index": "analyzed", "type": "integer 
"src as": ( "index": "analyzed", "type": "integer" 
"dst as": ( "index": "analyzed", "type": "integer" 
"src mask": ( "index": "analyzed", "type": "intege 


"dst mask": { "index": "analyzed", "type": "intege 


at 8 ES 46 (+ (Filter) 


丰富 的 过 滤器 插件 的 存在 是 logstash 威力 如 此 强大 的 重要 因素 。 名 为 过 滤器 ， 其 实 
提供 的 不 单单 是 过 滤 的 功能 。 在 本 章 我 们 就 会 重点 介绍 几 个 插件 ， 它 们 扩展 了 进入 
过 滤器 的 原始 数据 ， 进 行 复杂 的 逻辑 处 理 ， 甚 至 可 以 无 中 生 有 的 添加 新 的 logstash 
事件 到 后 续 的 流程 中 去 ! 


By Ja] 2b (Date) 
ZS y CARH 5 filters/date 插件 可 以 用 来 转换 你 的 日 志 记 录 中 的 时 间 字 符 串 ， 
变 成 LogStash::Timestamp 对 象 ， 然 后 转 存 到 Qtimestamp 字段 里 。 


注意 : 因为 在 稍 后 的 outputs/elasticsearch 中 常用 的 %{+YYYY.MM.dd} 这 种 写 
法 必须 读 取 @timestamp 数据 ， 所 以 一 定 不 要 直接 删 掉 这 个 字段 保留 自己 的 字 
段 ， 而 是 应 该 用 filters/date 转换 后 删除 自己 的 字段 ! 


这 在 叶 入 昌 数 据 的 时 候 固然 非常 有 用 ， 而 在 实时 数据 处 理 的 时 候 同样 有 效 ， 因 为 一 
般 情况 下 数据 流程 中 我 们 都 会 有 缓冲 区 ， 导 致 最 终 的 实际 处 理 时 间 跟 事件 产生 时 间 
略 有 偏差 。 


小 贴 士 : 个 人 强烈 建议 打开 Nginx 的 access_log 配置 项 的 buffer 参数 ， 对 极限 响 
应 性 能 有 极 大 提升 ! 


配置 示例 


filters/date 插件 支持 五 种 时 间 格 式 : 


ISO8601 


类 似 "2011-04-19T03:44:01.103Z" 这 样 的 格式 。 有 具体 Z 后 面 可 以 有 "08:00" 也 可 以 
没有 ，".103" 这 个 也 可 以 没有 。 常 用 场景 里 来 说 ，Nginx 的 log format 配置 里 就 可 
以 使 用 $time_iso8601 变量 来 记录 请 求 时 间 成 这 种 格式 。 


UNIX 


UNIX 时 间 惟 格式 ， 记 录 的 是 从 1970 年 起 始 至 今 的 总 秒 数 。Squid 的 默认 日 志 格 式 
中 就 使 用 了 这 种 格式 。 


UNIX_MS 


这 个 时 间 稚 则 是 从 1970 年 起 始 至 今 的 总 毫秒 数 。 据 我 所 知 ，JavaScript 里 经 常 使 
用 这 个 时 间 格 式 。 


TAI64N 


TAI64N 格式 比较 少见 ， 是 这 个 样子 的 : 94000000052f88ea32489532c 。 我 目前 
只 知道 常见 应 用 中 ，qmail 会 用 这 个 格式 。 


Joda-Time 库 


Logstash 内 部 使 用 了 Java 的 Joda 时 间 库 来 作 时 间 处 理 。 所 以 我 们 可 以 使 用 Joda 
库 所 支持 的 时 间 格 式 来 作 具 体 定 义 。Joda 时 间 格 式 定义 见 下 表 : 


时 间 格 式 


Symbol Meaning Presentation Examples 


G era text AD 
C century of era (2-0) number 20 
Y year of era (>=0) year 1996 
x weekyear year 1996 
Ww week of weekyear number 27 
e day of week number 2 
E day of week text Tuesday; Tue 
y year year 1996 
D day of year number 189 
M month of year month July; Jul; 07 
d day of month number 10 
a halfday of day text PM 
hour of halfday 
(0-11) number 0 
clockhour of halfday 
h (1-12) number 12 
H hour of day (0-23) number 0 
clockhour of day 
k (1724) number 24 
m minute of hour number 30 
second of minute number 55 
S fraction of second number 978 
Pacific Standard Time; 
Z time zone text PST 
Z time zone offset/id zone “URUN Up uke: 
America/Los_Angeles 
j escape for text delimiter 
li single quote literal ' 
http://joda- 


time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html 


下 面 我 们 写 一 个 Joda 时 间 格 式 的 配置 作为 示例 : 


filter { 
grok ( 
match => ["message", "%{HTTPDATE: logdate}" ] 
} 
date { 
match => ["logdate", "dd/MMM/yyyy:HH:mm:ss Z"] 
} 


注意 : 时 区 偏 移 量 只 需要 用 一 个 字母 z "Te 


时 区 问题 的 解释 


很 多 中 国 用 户 经 常 提 一 个 问题 : 为 什么 (timestamp 比 我 们 晚 了 8 个 小 时 ? 怎么 修 
改 成 北京 时 间 ? 

其 实 ，Elasticsearch 内 部 ， 对 时 间 类 型 字段 ， 是 统一 采用 UTC HA * Fm long 
长 整形 数据 的 |! 对 日 志 统 一 采用 UTC 时 间 存 储 ， 是 国际 安全 / 运 维 界 的 一 个 通 识 
欧美 公司 的 服务 器 普遍 广泛 分 布 在 多 个 时 区 里 一 一 不 像 中 国 ， 地 域 横 跨 五 个 时 
区 却 只 用 北京 时 间 。 








对 于 页 面 查看 ，ELK 的 解决 方案 是 在 Kibana 上 ， 读 取 浏 览 器 的 当前 时 区 ， 然 后 在 
页 面 上 转换 时 间 内 容 的 显示 。 

所 以 ， 建 议 大 家 接受 这 种 设 定 。 和 否则， 即便 你 用 .getLocalTime 修改 ， 也 还 要 
面临 在 Kibana 上 反 过 去 修改 ， 以 及 Elasticsearch 原 有 的 ["now-1h" TO 
"now"] 这 种 方便 的 搜索 语句 无 法 正常 使 用 的 槛 入 o 


以 上 ， 请 读者 自行 革 酌 。 


Grok 正则 捕获 


Grok 是 Logstash 最 重要 的 插件 。 你 可 以 在 grok 里 预定 义 好 命名 正则 表达 式 ， 在 
稍 后 (grok 参 数 或 者 其 他 正则 表达 式 里 ) 引 用 它 。 


正则 表达 式 语法 


运 维 工程 师 多 多 少 少 都 会 一 点 正则 。 你 可 以 在 grok 里 写 标准 的 正则 ， 像 下 面 这 
样 : 


\s+(?<request_time>\d+(?:\.\d+)?)\s+ 


Toric unc ae ren B A eS hon 
程序 员 可 能 更 习惯 写 (?P«name»pattern) ， 没 办 法 ， 适 应 一 下 吧 。 


现在 给 我 们 的 配置 文件 添加 第 一 个 过 滤器 pire 。 配置 要 添加 在 输入 和 输出 区 段 
之 间 (logstash 执行 区 段 的 时 候 并 不 依赖 于 次 序 ， 不 过 为 了 自己 看 得 方便 ， 还 是 按 次 
序 书写 吧 ) : 


input {stdin{}} 
filter { 
grok { 
match => { 
"message" => "\st+(?<request_time>\d+(?:\.\d+)?)\st" 


} 
output {stdout{codec => rubydebug}} 


运行 logstash 进程 然后 输入 "begin 123.456 end"， 你 会 看 到 类 似 下 面 这 样 的 输 
d: 


"message" => "begin 123.456 end", 
"@version" => "1", 
"@timestamp" => "2014-08-09T11:55:38.186Z", 
"host" => "raochenlindeMacBook-Air.local", 
"request_time" => "123.456" 


漂亮 ! 不 过 数据 类 型 好 像 不 太 满 意 ......request time 应 该 是 数值 而 不 是 字符 串 。 


我 们 已 经 提 过 稍 后 会 学 习 用 LogStash::Filters::Mutate 来 转换 字段 值 类 型 ， 
不 过 在 grok 里 ， 其 实 有 自己 的 魔法 来 实现 这 个 功能 |! 


Grok 表达 式 语法 


Grok 支持 把 预定 义 的 grok 表达 式 写 入 到 文件 中 ， 官 方 提供 的 预定 义 grok RAK 
JL : https://github.com/logstash-plugins/logstash-patterns- 
core/tree/master/patterns ° 


注意 : 在 新 版 本 的 logstash 里 面 ，pattern 目 录 已 经 为 室 ， 最 后 一 个 commit 提 示 
core patterns 将 会 由 logstash-patterns-core gem 来 提供 ， 该 目录 可 供用 户 存 放 
自 定 义 patterns 


下 面 是 从 官方 文件 中 摘抄 的 最 简单 但 是 足够 说 明 用 法 的 示例 : 


USERNAME [a-zA-Z0-9. -]* 
USER %{USERNAME} 


第 一 行 ， 用 普通 的 正则 表达 式 来 定义 一 个 grok 表达 式 ; 第 二 行 ， 通 过 打印 赋值 格 
式 (sprintf format)， 用 前 面 定 义 好 的 grok 表达 式 来 定义 另 一 个 grok 表达 式 。 


grok 表达 式 的 打印 赋值 格式 的 完整 语法 是 下 面 这 样 的 : 


%{PATTERN_NAME: capture_name:data_type} 


小 贴 士 : data type 目前 只 支持 两 个 值 : int 和 float 。 


所 以 我 们 可 以 改进 我 们 的 配置 成 下 面 这 样 : 


filter { 
grok ( 
match => { 
"message" => "%{WORD} %{NUMBER:request_time:float} % 
{WORD}" 


重新 运行 进程 然后 可 以 得 到 如 下 结果 : 


{ 
"message" => "begin 123.456 end", 
"@version" => "1", 
"@timestamp" => "2014-08-09T12:23:36.634Z", 
"host" => "raochenlindeMacBook-Air.local", 
"request_time" => 123.456 
} 


这 次 request time 变 成 数值 类 型 了 。 


最 佳 实践 


实际 运用 中 ， 我 们 需要 处 理 各 种 各 样 的 日 志文 件 ， 如 果 你 都 是 在 配置 文件 里 各 自 写 
一 行 自己 的 表达 式 ， 就 完全 不 可 管理 了 了。 所以， 我们 建议 是 把 所 有 的 grok 表达 式 
统一 写 入 到 一 个 地 方 。 然 后 用 filter/grok 的 patterns dir 选项 来 指明 。 

如 果 你 把 "message" 里 所 有 的 信息 都 grok 到 不 同 的 字段 了 ， 数 据 实质 上 就 相当 于 
是 重复 存储 了 两 份 。 所 以 你 可 以 用 remove field 参数 来 删除 掉 message F 
段 ， 或 者 用 overwrite 参数 来 重 写 默认 的 message 字段 ， 只 保留 最 重要 的 部 


o 


学 g 


重 写 参数 的 示例 如 下 : 


filter 1 
grok ( 
patterns dir -» ["/path/to/your/own/patterns" ] 
match => { 
"message" => "%{SYSLOGBASE} %{DATA:message}" 
} 


overwrite => ["message"] 


$ £4 X grok 正则 性 能 的 最 佳 实践 ( timeout_millis 等 )， 
IL : https://www.elastic.co/blog/do-you-grok-grok 


小 贴 士 
多 行 匹配 


在 和 codec/multiline 搭配 使 用 的 时 候 ， 需 要 注意 一 个 问题 ，grok 正则 和 普通 正则 一 
样 ， 默 认 是 不 支持 匹配 回 车 换行 的 。 就 像 你 需要 =~ //m 一 样 也 需要 单独 指定 ， 
具体 写法 是 在 表达 式 开 始 位 置 加 (?m) 标记 。 如 下 所 示 : 


match => { 
"message" => "(?m)\s+(?<request_time>\d+(?:\.\d+)?)\st" 


多 项 选择 


有 时 候 我 们 会 碰 上 一 个 日 志 有 多 种 可 能 格式 的 情况 。 这 时 候 要 写成 单一 正则 就 比较 
困难 ， 或 者 全 用 | 隔 开 又 比较 于 质 。 这 时 候 ，logstash 的 语法 提供 给 我 们 一 个 有 
趣 的 解决 方式 。 


文档 中 ， 都 说 明 logstash/filters/grok 插件 的 match 参数 应 该 接受 的 是 一 个 Hash 
值 。 但 是 因为 早期 的 logstash 语法 中 Hash 值 也 是 用 [] 这 种 方式 书写 的 ， 所 以 
其 实现 在 传递 Array 值 给 match 参数 也 完全 没 问 题 。 所 以 ， 我 们 这 里 其 实 可 以 传 
递 多 个 正则 来 匹配 同一 个 字段 : 


match => [ 
"message", "(?<request_time>\d+(?:\.\d+)?)", 
"message", "%{SYSLOGBASE} %{DATA:message}", 
"message", "(?m)%{WORD}" 


logstash 会 按照 这 个 定义 次 序 依次 尝试 匹配 ， 到 匹配 成 功 为 止 。 虽 说 效果 跟 用 | 
分 割 写 个 大 大 的 正则 是 一 样 的 ， 但 是 可 阅读 性 好 了 很 多 。 


最 后 也 是 最 关键 的 ， 我 强烈 建议 每 个 人 都 要 使 用 Grok Debugger 来 调试 自己 的 
grok 表达 式 。 


dissect 


grok 作为 Logstash 最 广为人知 的 插件 ， 在 性 能 和 资源 损耗 方面 同样 也 广 为 诉 病 。 
为 了 应 对 这 个 情况 ， 同 时 也 考虑 到 大 多 数 时 候 ， 日 志 格式 并 没有 那么 复杂 ， 
Logstash 开发 团队 在 5.0 版 新 添加 了 另 一 个 解析 字段 的 插件 : dissect。 


当日 志 格 式 有 比较 简明 的 分 隔 标 志 位 ， 而 且 重 复 性 较 大 的 时 候 ， 我 们 可 以 使 用 
dissect 插件 更 快 的 完成 解析 工作 。 下 面 是 解析 syslog 的 示例 : 


示例 


filter { 
dissect { 
mapping => { 
"message" => "%{ts} %{+ts} %{+ts} %{src} %{} %{prog} 
[%{pid}]: %{msg}" 
} 
convert_datatype => { 
pid => "int" 


语法 解释 


我 们 看 到 上 面 使 用 了 和 Grok 很 类 似 的 %{} 语法 来 表示 字段 ， 这 显然 是 基于 习惯 
延续 的 考虑 。 不 过 示例 中 %{+ts} 的 加 号 就 不 一 般 了 。dissect 除了 字段 外 面 的 字 
符 串 定位 功能 以 外 ， 还 通过 几 个 特殊 符号 来 处 理 字段 提取 的 规则 : 


e %{+key} 这 个 + 表示 ， 前 面 已 经 捕获 到 一 个 key 字段 了 ， 而 这 次 捕获 的 内 
容 ， 自 动 添补 到 之 前 key 字段 内 容 的 后 面 。 

e 9%{+key/2} 这 个 /2 RH? EAS KARA SAAS] key 字段 里 的 时 候 ， 拼 
接 字 符 串 的 顺序 谁 前 谁 后 。 /2 表示 排 第 2 位 。 

e %{?string} 这 个 ? 表示 ， 这 块 只 是 一 个 占 位 ， 并 不 会 实际 生成 捕获 字段 存 到 
Event 里 面 。 


e %{?string} %{&string} 当 同 样 捕获 名 称 都 是 string， 但 是 一 个 ? 一 个 & 的 
时 候 ， 表 示 这 是 一 个 键 值 对 。 


比如 对 http://rizhiyi.com/index.do?id-123 写 这 么 一 段 配置 : 


http://%{domain}/%{?url}?%{?argi}=%{&argi} 


则 最 终生 成 的 Event 内 容 是 这 样 的 : 


domain => "rizhiyi.com", 
id => "123" 


GeolP 地 址 查询 归 类 


GeolP 是 最 常见 的 免费 IP 地 址 归 类 查询 库 ， 同 时 也 有 收费 版 可 以 采购 。GeolP & 
可 以 根据 IP 地 址 提供 对 应 的 地 域 信息 ， 包 括 国 别 ， 省 市 ， 经 纬度 等 ， 对 于 可 视 化 
地 图 和 区 域 统计 非常 有 用 。 


配置 示例 


filter { 


geoip { 
source => "message" 


} 


Ww 


运行 结果 


filter Ae ;& 


"message" => "183.60.92.253", 
"@version" => "1", 
"@timestamp" => "2014-08-07T10:32:55.610Z", 
"host" => "raochenlindeMacBook-Air.local", 
"geoip" => { 
Tip! => 1183:50:02:2523!'^ 
"country code2" => "CN", 
"country_code3" => "CHN", 
"country_name" => "China", 
"continent_code" => "AS", 
"region_name" => "30", 
"city name" => "Guangzhou", 
"latitude" => 23.11670000000001, 
"longitude" => 113.25, 
"timezone" => "Asia/Chongqing", 
"real_region_name" => "Guangdong", 
"location" => [ 
[0] 113.25, 
[1] 23.11670000000001 


置 说 明 


GeolP 库 数 据 较 多 ， 如 果 你 不 需要 这 么 多 内 容 ， 可 以 通过 fields 选项 指定 自己 
所 需要 的 。 下 例 为 全 部 可 选 内 容 : 


filter 1 
geoip { 
fields -» ["city name", "continent code", "country code2 
", "country code3", "country name", "dma code", "ip", "latitude" 
, "longitude", "postal code", "region name", "timezone"] 


j 


需要 注意 的 是 : geoip.location 是 logstash 通过 latitude 和 longitude 
额外 生成 的 数据 。 所 以 ， 如 果 你 是 想 要 经 纬度 又 不 想 重复 数据 的 话 ， 应 该 像 下面 这 
样 做 : 


filter ( geoip { fields => ["city_name", "country code2", "country name", "latitude", 
"longitude", "region name"] remove field => ["[geoip][latitude]", "[geoip] 


[longitude]"] } ) `` 


小 贴 士 


geoip 插件 的 "source" 字段 可 以 是 任 一 处 理 后 的 字段 ， 比 如 "client_ip"， 但 是 字段 
内 容 却 需要 小 心 1 geoip 库 内 只 存 有 公共 网 络 上 的 IP 信息 ， 查 询 不 到 结果 的 ， 会 直 
接 返 回 null * 而 logstash 的 geoip 插件 对 null 结果 的 处 理 是 : 不 生成 对 应 的 
geoip. 字 段 。 


所 以 读者 在 测试 时 ， 如 果 使 用 了 诸如 127.0.0.1, 172.16.0.1, 192.168.0.1, 10.0.0.1 
等 内 网 地 址 ， 会 发 现 没 有 对 应 输出 ! 


JSON 编 解 码 


在 上 一 章 ， 已 经 讲 过 在 codec 中 使 用 JSON 编码 。 但 是 ， 有 些 日 志 可 能 是 一 种 复 
合 的 数据 结构 ， 其 中 只 是 一 部 分 记录 是 JSON 格式 的 。 这 时 候 ， 我 们 依然 需要 在 
filter 阶段 ， 单 独居 用 JSON 解码 插件 。 


配置 示例 


filter { 
json { 
source => "message" 
target => "jsoncontent" 


WwW 


运行 结果 


~ 


"@version": "1", 
"Qtimestamp": "2014-11-18T08:11:33.000Z", 
"host": "web121.mweibo.tc.sinanode.com", 
"message": "{\"uid\":3081609001, \"type\":\"signal\"}", 
"jsoncontent": { 
"uid": 3081609001, 
"type": "signal" 


小 贴 士 


如 果 不 打算 使 用 多 层 结构 的 话 ， 删 掉 target 配置 即 可 。 新 的 结果 如 下 : 


"Qversion": "i", 

"Qtimestamp": "2014-11-18T08:11:33.000Z", 

"host": "web121.mweibo.tc.sinanode.com", 

"message": "{\"uid\":3081609001, \"type\":\"signal\"}", 
"uid": 3081609001, 

"type": "signal" 


Key-Value 7 


在 很 多 情况 下 ， 日 志 内 容 本 身 都 是 一 个 类 似 于 key-value 的 格式 ， 但 是 格式 具体 的 
样式 却 是 多 种 多 样 的 。logstash 提供 filters/kv 插件 ， 帮 助 处 理 不 同样 式 的 
key-value 日 志 ， 变 成 实际 的 LogStash::Event 数据 。 


配置 示例 
filter { 
ruby { 
init => "@kname = ['method', 'uri', 'verb']" 
code => " 


new event = LogStash: :Event.new(Hash[@kname.zip(even 
t.get('request').split('|'))]) 

new_event.remove('@timestamp' ) 

event.append(new event) 


} 
if [uri] { 
ruby { 
init => "@kname = ['url_path', 'url_args']" 
code => " 


new event = LogStash: :Event.new(Hash[@kname.zip( 
event.get('uri').split('?'))]) 

new event.remove('Qtimestamp') 

event.append(new event) 


j 
kv { 

prefix => "url_" 

source => "url_args" 

field_split => "&" 

remove_field => [ "url_args", "uri", "request" ] 
} 


解释 


Nginx 访问 日 志 中 的 $request ， 通 过 这 段 配置 ， 可 以 详细 切 分 成 method , 


url path , verb , url_a, url b 


进一步 的 ， 如 果 url args 中 有 过 多 字段 ， 可 能 导致 Elasticsearch 集群 因为 频繁 
update mapping 或 者 消耗 太 多 内 存在 cluster state 上 而 宕 机 。 所 以 ， 更 优 的 选择 ， 
是 只 保留 明确 有 用 的 url args 内 容 ， 其 他 部 分 使 去。 


kv { 
prefix => "url " 
source -» "url args" 
field split -» "&" 
include_keys => [ "uid", "cip" ] 
remove_field => [ "url_args", "uri", "request" ] 


上 例 即 表示 ， 除 了 url uid 和 url cip 两 个 字段 以 外 ， 其 他 的 url_* 都 不 
保留 。 


数值 统计 (Metrics) 


filters/metrics 插件 是 使 用 Ruby 的 Metriks 模块 来 实现 在 内 存 里 实时 的 计数 和 采样 
分 析 。 该 模块 支持 两 个 类 型 的 数值 分 析 : meter 和 timer。 下 面 分 别 举例 说 明 : 


Meter :; | (38 £ I] 4& 16 20) 


web i2 H E SH SR LAE ZEE TRA. JESE ASA PRE o 38 8 RA AS C 
法 ， 是 通过 logstash 或 者 其 他 日 志 分 析 脚 本 ， 把 计数 发 送 到 rrdtool 或 者 graphite 
里 面 。 然 后 再 通过 check-graphite 脚本 之 类 的 东西 来 检查 异常 并 报警 。 


事实 上 这 个 事情 可 以 直接 在 logstash 内 部 就 完成 。 比 如 如 果 最 近 一 分 钟 504 请 求 
的 个 数 超过 100 个 就 报警 : 


filter { 
metrics { 
meter => "error_%{status}" 
add_tag => "metric" 
ignore_older_than => 10 
} 
if "metric" in [tags] { 
ruby { 
code => "event.cancel if (event.get('[error_504][rat 
e_1m]') * 60 > 100)" 


} 
} 
} 
output { 
if "metric" in [tags] { 
exec { 
command => "echo \"Out of threshold: %{[error_504][r 
ate 1m])^"" 


j 


这 里 需要 注意 *eo 的 含义 。 


metriks 模块 生成 的 rate 1m/bm/15m 意思 是 : 最 近 1，5，15 分 钟 的 每 秒 速率 ! 


Timer 示例 (box and whisker 异常 检测 ) 


官 版 的 fi/ters/metrics 插件 只 适用 于 metric 事件 的 检查 。 由 插件 生成 的 新 事件 内 部 
不 存 有 来 自 input 区 段 的 实际 数据 信息 。 所 以 ， 要 完成 我 们 的 百分比 分 布 箱 体 检 

测 ， 需 要 首先 对 代码 稍微 做 几 行 变动 ， 即 在 metric 的 timer 事件 里 加 一 个 属性 ， 存 
储 最近 一 个 实际 事件 的 数 

值 : https://github.com/chenryn/logstash/commit/bc7 bf34caf551d8a149605cf28e7 
c5d33fae7458 


有 了 这 个 last 值 ， 然 后 我 们 就 可 以 用 如 下 配置 来 探测 异常 数据 了 : 


filter { 
metrics { 
timer => {"rt" => "%{request_time}"} 
percentiles => [25, 75] 
add_tag => "percentile" 
J 
if "percentile" in [tags] { 
ruby { 
code => "]zevent.get('[rt][p75]')-event.get('[rt] [p2 
5]');event.set('[rt][low]', event.get('[rt][p25]')-1);event.set( 
' [rt] [high] ', event.get('[rt][p75] ' ) 2)" 
} 


} 
output { 
if "percentile" in [tags] and ([rt][last] > [rt][high] or [r 
t][last] < [rt][low]) { 
exec { 
command => "echo \"Anomaly: %{[rt][last]}\"" 


小 贴 士 : 4 X box and shisker plot 内 容 和 重要 性 ， 参 见 《 数 据 之 魅 》 一 书 。 


数据 修改 (Mutate) 


filters/mutate 插件 是 Logstash 另 一 个 重要 插件 。 它 提供 了 丰富 的 基础 类 型 数据 处 
理 能 力 。 包 括 类 型 转换 ， 字 符 串 处 理 和 字段 处 理 等 。 


类 型 转换 


类 型 转换 是 filters/mutate 插件 最 初 诞生 时 的 唯一 功能 。 其 应 用 场景 在 之 前 
Codec/JSON 小 节 已 经 提 到 。 


可 以 设置 的 转换 类 型 包括 : "integer"，"float" 和 "string"。 示 例如 下 : 


filter 1 
mutate ( 
convert -» ["request time", "float"] 


注意 : mutate 除了 转换 简单 的 字符 值 ， 还 支持 对 数组 类 型 的 字段 进行 转换 ， 即 将 
['1","2"] 转换 成 [1,2] 。 但 不 支持 对 哈 布 类 型 的 字段 做 类 似 处 理 。 有 这 方面 
需求 的 可 以 采用 稍 后 讲述 的 filters/ruby 插件 完成 。 


字符 串 处 理 
e gsub 


AQIS F AF HAL HF LAL aK 


gsub => ["urlparams", "[\\?#]", " "] 


e split 


filter 1 
mutate ( 
split => ["message", "|"] 


随意 输入 一 串 以 | PBA FH > mde "123|321|adfdldfjld*=123"， 可 以 看 到 如 下 和 输 
出 : 


{ 
"message" => [ 
Loy "423". 
[3]932 35 
[2] "adfud" 
[ep digids*-T29* 
], 
"aversion => "i", 
"@timestamp" => "2014-08-20T15:58:23.120Z", 
"host" => "raochenlindeMacBook-Air.local" 
} 
e join 


仅 对 数组 类 型 字段 有 效 


我 们 在 之 前 已 经 用 split 逢 切 的 基础 再 join 回去 。 配 置 改 成 : 


filter ( 
mutate ( 
split => ["message", "|"] 
} 
mutate { 
join => ["message", ","] 


filter 区 段 之 内 ， 是 顺序 执行 的 。 所 以 我 们 最 后 看 到 的 输出 结果 是 : 


filter Ec £ 


"message" => "123,321, adfd,dfjld*=123", 


"2014-08 -20T16:01:33.972Z", 


"host" => "raochenlindeMacBook-Air.local" 


{ 
"e@version” => Up 
"@timestamp" => 

} 

e merge 


合并 两 个 数组 或 者 哈 希 字段 。 依 然 在 之 前 split 的 基础 上 继续 : 


filter { 
mutate { 
split 
} 
mutate { 
merge 


我 们 会 看 到 输出 : 


"message" => 
[ode 23. 
[ie s2i 
[21 “adrd", 
[3] 
[4] 
[5] 
[6] 
[7] 


upou 
Ae 
erolicl 


], 
"@version" => 
"@timestamp" => 


"hos te! => 


=> ["message", 


=> ["message", 


iE] 


"message" | 


[ 


a 1201 


üt 162 3 


ques 
12014-08-200716:05:53- 7412", 
"raochenlindeMacBook-Air.local" 


如 果 src 字段 是 字符 串 ， 会 自动 先 转换 成 一 个 单元 素 的 数组 再 合并 。 把 上 一 示例 中 
的 来 源 字段 改 成 "host" : 


filter { 
mutate { 
split => ["message", "|"] 
} 
mutate { 
merge => ["message", "host"] 
} 
} 
结果 变 成 
{ 
"message" => [ 
[eo] sie 
EW 2 
[2] adfds 
[3] "dfjld*-123", 
[4] "raochenlindeMacBook-Air.local" 
], 
Ovens Tondi = >> 
"@timestamp" => "2014-08-20T16:07:53.533Z", 
"host" => [ 
[0] "raochenlindeMacBook-Air.local" 
] 
} 


看 ， 目 的 字段 "message" 确实 多 了 一 个 元 素 ， 但 是 来 源 字段 "host" 本 身 也 由 字符 
串 类 型 变 成 数组 类 型 了 | 


下 面 你 猜 ， 如果 来 源 位 置 写 的 不 是 字段 名 而 是 直接 一 个 字符 囊 ， 会 产生 什么 奇特 的 
ARR? 


e strip 
e lowercase 
e uppercase 


字段 处 理 
e rename 


重 命名 某 个 字段 ， 如 果 目 的 字段 已 经 存在 ， 会 被 覆盖 掉 : 


filter { 
mutate { 
rename => ["syslog_host", "host" ] 


e update 
更 新 某 个 字段 的 内 容 。 如 果 字 段 不 存在 ， 不 会 新 建 。 
e replace 


作用 和 update 类 似 ， 但 是 当 字 段 不 存在 的 时 候 ， 它 会 起 到 add field 参数 一 样 
的 效果 ， 自 动 添加 新 的 字段 。 


执行 次 序 


需要 注意 的 是 ，filter/mutate 内 部 是 有 执行 次 序 的 。 其 次 序 如 下 : 


rename(event) if @rename 
update(event) if @update 
replace(event) if @replace 
convert(event) if @convert 
gsub(event) if @gsub 
uppercase(event) if @uppercase 
lowercase(event) if Qlowercase 
strip(event) if Qstrip 
remove(event) if Qremove 
split(event) if Qsplit 
join(event) if @join 
merge(event) if Qmerge 


filter matched(event) 


而 filter matched 这 个 filters/base.rb 里 继承 的 方法 也 是 有 次 序 的 。 


Qadd field.each do |field, value| 
end 

Qremove field.each do |field| 

end 

Qadd tag.each do |tag| 

end 

Qremove tag.each do |tag| 

end 


随心 所 欲 的 Ruby 处 理 


如 果 你 稍微 懂 那 么 一 点 点 Ruby 语法 的 话 ，filters/ruby 插件 将 会 是 一 个 非常 有 用 的 
工具 。 


比如 你 需要 稍微 修改 一 下 LogStash::Event 对 象 ， 但 是 又 不 打算 为 此 写 一 个 完 
整 的 插件 ， 用 filters/ruby 插件 绝对 感觉 良好 。 


配置 示例 


filter { 
ruby { 
init => "@kname = ['client','servername','url','status', 
'time', 'size', 'upstream', 'upstreamstatus', 'upstreamtime', 'refere 
r', 'xff', 'useragent']" 
code => " 
new event = LogStash: :Event.new(Hash[@kname.zip(even 
t.get('message').split('|'))]) 
new event.remove('Qtimestamp') 
event.append(new event)" 


官网 示例 是 一 个 比较 有 趣 但 是 没 啥 大 用 的 做 法 随机 取消 90% 的 事件 。 





所 以 上 面 我 们 给 出 了 一 个 有 用 而 且 强 大 的 实例 。 


解释 


nb» 


通常 我 们 都 是 用 filters/grok 插件 来 捕获 字段 的 ， 但 是 正则 耗费 大 量 的 CPU 资源 ， 
很 容易 成 为 Logstash 进程 的 瓶颈 。 


而 实际 上 ， 很 多 流 经 Logstash 的 数据 都 是 有 自己 预定 义 的 特殊 分 隔 符 的 ， 我 们 可 
以 很 简单 的 直接 切割 成 多 个 字段 。 


filters/mutate 插件 里 的 "split" 选项 只 能 切 成 数组 ， 后 续 很 不 方便 使 用 和 识别 。 而 在 
filters/ruby 里 ， 我 们 可 以 通过 "init" 参数 预定 义 好 由 每 个 新 字段 的 名 字 组 成 的 数 
组 ， 然 后 在 "code" 参数 指定 的 Ruby 语句 里 通过 两 个 数组 的 Zip 操作 生成 一 个 哈 硕 
并 添加 进 数 组 里 。 短 短 一 行 Ruby 代码 ， 可 以 减少 50% 以 上 的 CPU 使 用 率 。 


注 1 : 从 Logstash-2.3 开始 ， LogStash::Event.append 不 再 直接 接受 Hash 对 
象 ， 而 必须 是 LogStash: :Event 对 象 。 所 以 示例 变 成 要 先 初 始 化 一 个 新 event * 
再 把 无 用 的 gtimestamp 移 除 ， 再 append 进去 。 否 则 会 把 Qtimestamp ŽA 
有 两 个 时 间 的 数组 了 | 


注 2 : 从 Logstash-5.0 开始 ， LogStash::Event 7X7 Java 实现 ， 直 接 使 用 
event["parent"]["child"] 形式 获取 的 不 是 原 事件 的 引用 而 是 复制 品 。 需 要 改 
用 event.get('[parent][child]') 和 event.set('[parent][child]', 
'value') 的 方法 。 


filters/ruby 插件 用 途 远 不 止 这 一 点 ， 下 一 节 你 还 会 继续 见 到 它 的 身影 。 


更 多 实例 
2014 年 09 # 23 日 新 增 


filter( 
date { 
match => ["datetime" , "UNIX"] 


j 
ruby { 
code => "event.cancel if 5 * 24 * 3600 < (event['@timest 
amp']-::Time.now).abs" 


} 


在 实际 运用 中 ， 我 们 几乎 肯定 会 碰 到 出 乎 意料 的 输入 数据 。 这 都 有 可 能 导致 
Elasticsearch 集群 出 现 问 题 。 


当 数 据 格式 发 生变 化 ， 比 如 UNIX 时 间 格 式 变 成 UNIX_MS HBA? SSK 
logstash AJEG EH KI] > REFMAN 


或 者 误 输 入 过 老 的 数据 时 ， 因 为 一 般 我 们 会 close 几 天 之 前 的 索引 以 节省 内 存 ， 必 
要 时 再 打开 。 而 直接 尝试 把 数据 写 入 被 关闭 的 索引 会 导致 内 存 问 题 。 

这 时 候 我 们 就 需要 提前 校 验 数据 的 合法 性 。 上 面 配 置 ， 就 是 用 于 过 滤 掉 时 间 范 围 与 
当前 时 间 差 距 太 大 的 非法 数据 的 。 


split 拆 分 事件 


上 一 章 我 们 通过 multiline 插件 将 多 行 数据 合并 进 一 个 事件 里 ， 那 么 反 过 来 ， 也 可 以 
把 一 行 数据 ， 拆 分 成 多 个 事件 。 这 就 是 split 插件 。 


配置 示例 


filter { 
split { 
field => "message" 
terminator => "#" 


} 
} 
运行 结果 


这 个 测试 中 ， 我 们 在 intputs/stdin 的 终端 中 输入 一 行 数据 : "test1#test2"， 结 果 看 
到 输出 两 个 事件 : 


{ 
"@version": "1", 
"Qtimestamp": "2014-11-18T08:11:33.000Z", 
"host": "web121.mweibo.tc.sinanode.com", 
"message": "testi" 

} 

{ 
"@version": "1", 
"Qtimestamp": "2014-11-18T08:11:33.000Z", 
"host": "web121.mweibo.tc.sinanode.com", 
"message": "test2" 

} 


重要 提示 


split 插件 中 使 用 的 是 yield 功能 ， 其 结果 是 split 出 来 的 新 事件 ， 会 直接 结束 其 在 
filter 阶段 的 历程 ， 也 就 是 说 写 在 split 后 面 的 其 他 filter 插件 都 不 起 作用 ， 进 入 到 
output 阶段 。 所 以 ， 一 定 要 保证 split 配置 写 在 全 部 filter 配置 的 最 后 。 


使 用 了 类 似 功能 的 还 有 clone 插件 。 


iz : 从 logstash-1.5.0beta1 版 本 以 后 修复 该 问题 。 


elapsed 


filter { 
grok { 
match => ["message", "%{TIMESTAMP_ISO8601} START id: (?<task 
zd y] 
add tag => [ "taskStarted" ] 
} 
grok { 
match => ["message", "%{TIMESTAMP_ISO8601} END id: (?<task_i 
d>.*)"] 
add tag => [ "taskTerminated" | 
} 
elapsed { 
start_tag => "taskStarted" 
end_tag => "taskTerminated" 
unique_id_field => "task_id" 


保存 进 Elasticsearch 


Logstash 可 以 使 用 不 同 的 协议 实现 完成 将 数据 写 入 Elasticsearch 的 工作 。 在 不 同 
时 期 ， 也 有 不 同 的 插件 实现 方式 。 本 节 以 最 新 版 为 准 ， 即 主要 介绍 HTTP 方式 。 同 
时 也 附带 一 些 原 有 的 node 和 transport 方式 的 介绍 。 


配置 示例 


output { 
elasticsearch { 

hosts => ["192.168.0.2:9200" | 
index => "logstash-%{type}-%{+YYYY.MM.dd}" 
document_type => "%{type}" 
flush size => 20000 
idle flush time => 10 
sniffing -» true 
template overwrite -» true 


批量 发 送 


在 过 去 的 版 本 中 ， 主 要 由 本 插件 的 flush size 和 idle flush time 两 个 参 
数 共 同 控制 Logstash 向 Elasticsearch 发 送 批量 数据 的 行为 。 以 上 面 示例 来 说 : 
Logstash 会 努力 摸 到 20000 条 数据 一 次 性 发 送出 去 ， 但 是 如 果 10 HPA MAG 
20000 条 ，Logstash 还 是 会 以 当前 攒 到 的 数据 量 发 一 次 。 


默认 情况 下 ， flush size 是 500 
AKT flush size 也 没 能 提高 
AE © 





& > idle flush time 是 1 秒 。 这 也 是 很 多 
号 1 


入 ES 性 能 的 原 Logstash 还 是 


从 5.0 开始 ， 这 个 行为 有 了 另 一 个 前 提 : flush size 的 大 小 不 能 超过 Logstash 
运行 时 的 命令 行 参 数 设 置 的 batch size ， 和 否则 将 以 batch size 为 批量 发 送 
的 大 小 。 


索引 名 


写 入 的 ES 索引 的 名 称 ， 这 里 可 以 使 用 变量 。 为 了 更 贴 合 日 志 场 景 ，Logstash 提供 
了 %{+YYYY.MM.dd} 这 种 写法 。 在 语法 解析 的 时 候 ， 看 到 以 + 号 开头 的 ， 就 会 自 
动 认为 后 面 是 时 间 格 式 ， 尝 试用 时 间 格 式 来 解析 后 续 字 符 串 。 所 以 ， 之 前 处 理 过 程 
中 不 要 给 自 定 义 字 段 取 个 加 号 开头 的 名 字 ...... 


此 外 ， 注 意 索 引 名 中 不 能 有 大 写字 母 ， 否 则 ES 在 日 志 中 会 报 
InvalidiIndexNameException， 但 是 Logstash TAIR > ix 4-48 3X HEAR IRB > WE 
易 掉 进 这 个 坑 中 。 


Logstash 1.4.2 在 transport 和 http 协议 的 情况 下 是 固定 连接 指定 host 发 送 数 据 。 
从 1.5.0 开始 ，host 可 以 设置 数组 ， 它 会 从 节点 列表 中 选取 不 同 的 节点 发 送 数 据 ， 
达到 Round-Robin 负载 均衡 的 效果 。 


不 同 版 本 的 协议 沿革 


1.4.0 版 本 之 前 ， 有 logstash-output-elasticsearch , logstash-output- 


elasticsearch_http , logstash-output-elasticsearch river 三 个 插件 。 


1.4.0 到 2.0 版 本 之 间 ， 配 合 Elasticsearch 废弃 river 方法 ， 只 剩 下 logstash- 

output-elasticsearch 一 个 插件 ， 同 时 实现 了 node ^ transport ` http 三 种 协 

Du 

2.0 版 本 开始 ， 为 了 兼容 性 和 调试 方便 ， logstash-output-elasticsearch ;X 

为 只 支持 http 协议 。 想 继续 使 用 node 或 者 transport 协议 的 用 户 ， 需 要 单独 安装 
logstash-output-elasticsearch java 插件 。 


一 个 小 集群 里 ， 使 用 node 协议 最 方便 了 。Logstash 以 elasticsearch 的 client 节点 
身份 ( 即 不 存 数 据 不 参加 选举 ) 运 行 。 如 果 你 运行 下 面 这 行 命令 ， 你 就 可 以 看 到 自己 
的 logstash 进程 名 ， 对 应 的 node.role 值 是 Cc: 


# curl 127.0.0.1:9200/ cat/nodes?v 


host ip heap.percent ram.percent load node.role maste 
r name 

local 192.168.0.102 7 C - logstash-local-1036 
-2012 

local 192.168.0.2 7 d i Sunstreak 


Logstash-1.5 RE > 4,75 FE2- X — ^ o HA elasticsearch 服务 器 。 如 果 你 想 变 更 
node 协议 下 的 这 些 配置 ， 在 s$PWD/elasticsearch.yml 文件 里 写 自 定义 配置 即 
"I > logstash 会 尝试 自动 加 载 这 个 文件 。 


对 于 拥有 很 多 索引 的 大 集群 ， 你 可 以 用 transport 协议 。logstash 进程 会 转发 所 有 
数据 到 你 指定 的 某 台 主机 上 。 这 种 协议 跟 上 面 的 node 协议 是 不 同 的 。hnode 协议 下 
的 进程 是 可 以 接收 到 整个 Elasticsearch 集群 状态 信息 的 ， 当 进程 收 到 一 个 事件 

时 ， 它 就 知道 这 个 事件 应 该 存在 集群 内 哪个 机 器 的 分 片 里 ， 所 以 它 就 会 直接 连接 该 
机 器 发 送 这 条 数据 。 而 transport 协议 下 的 进程 不 会 保存 这 个 信息 ， 在 集群 状态 更 
新 (节点 变化 ， 索 引 变化 都 会 发 送 全 量 更 新 ) 时 ， 就 不 会 对 所 有 的 logstash 进程 也 发 
送 这 种 信息 。 更 多 Elasticsearch 集群 状态 的 细节 ， 参 阅 本 书后 续 章节 。 


小 贴 士 


e 经 常 有 同学 问 ， 为 什么 Logstash 在 有 多 个 conf 文件 的 情况 下 ， 进 入 ES 的 数 
据 会 重复 ， 几 个 conf 数据 就 会 重复 几 次 。 其 实 问 题 原 因 在 之 前 局 动 参数 章节 
有 提 过 ，output 段 顺序 执行 ， 没 有 对 日 志 type 进行 判断 的 各 插件 配置 都 会 全 
部 执行 一 次 。 在 output 段 对 type 进行 判断 的 语法 如 下 所 示 : 


output { 
if [type] == "nginxaccess" { 
elasticsearch { } 
} 
} 
模板 


Elasticsearch 支持 给 索引 预定 义 设 置 和 mapping( 前 提 是 你 用 的 elasticsearch 版 本 
支持 这 个 API， 不 过 估计 应 该 都 支持 )。Logstash 自 带 有 一 个 优化 好 的 模板 ， 内 容 
如 下 : 


filter& £ 


{ 
"template" "logstash-*", 
"version" : 50001, 
"settings“ : { 
"index.refresh_interval" SS 
tr 
"mappings" : 4 
"dotrault-'- 
" all" : {"enabled" : true, "norms" : false}, 
"dynamic templates" L 
"message_field" { 
"path_match" "message", 
"match_mapping_type" SEITE 
"mapping" 
"type" = "text". 
"norms" : false 
} 
} 
} i 
"string_fields" { 
amate ate Nu 
"match mapping type" -SE 
"mapping" 
"type" ‘text “norms” + false, 
"fields" { 
"keyword" { "type": "keyword" } 
} 
} 
} 
+ |, 
"properties" : { 
"Qtimestamp": { "type": "date", "include in all" 
: false }, 
"@version": { "type": "keyword", "include in all" 
= false- > 
"geoip" : { 
"dynamic": true, 
"properties" { 
Pipe types Tp 
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“Location: { “type™ = “geo point” }. 








Vlatitude” € { type" sS "balf-float" 4, 
"Tongastude' (0 "type" S haTft-tlioate c. 
} 
} 
} 
} 
} 
} 
‘| =a —] s 
这 其 中 的 关键 设置 包括 : 


e template for index-pattern 


只 有 匹配 logstash-* 的 索引 才 会 应 用 这 个 模板 。 有 时 候 我 们 会 变更 Logstash 
的 默认 索引 名 称 ， 记 住 你 也 得 通过 PUT 方法 上 传 可 以 匹配 你 自 定 义 索引 名 的 模 

板 。 当 然 ， 我 更 建议 的 做 法 是 ， 把 你 自 定 义 的 名 字 放 在 "logstash-" 后 面 ， 变 成 
index => "logstash-custom-%{+yyyy.MM.dd}" 这 样 。 


e refresh_interval for indexing 


Elasticsearch 是 一 个 近 实 时 搜索 引擎 。 它 实际 上 是 每 1 秒 钟 刷新 一 次 数据 。 对 于 日 
志 分 析 应 用 ， 我 们 用 不 着 这 么 实时 ， 所 以 logstash 自 带 的 模板 修改 成 了 5 秒 钟 。 你 
还 可 以 根据 需要 继续 放大 这 个 刷新 间隔 以 提高 数据 写 入 性 能 。 


e multi-field with keyword 


Elasticsearch 会 自动 使 用 自己 的 默认 分 词 器 (空格 ， 点 ， 斜 线 等 分 割 ) 来 分 析 字 段 。 
分 词 器 对 于 搜索 和 评分 是 非常 重要 的 ， 但 是 大 大 降低 了 索引 写 入 和 聚合 请 求 的 性 
能 。 所 以 logstash 模板 定义 了 一 种 叫 "多 字段 "(multi-field) 类 型 的 字段 。 这 种 类 型 会 
自动 添加 一 个 ".keyword" 结尾 的 字段 ， 并 给 这 个 字段 设置 为 不 启用 分 词 嚣 。 简 单 
说 ， 你 想 获取 url 字段 的 聚合 结果 的 时 候 ， 不 要 直接 用 "Url"， 而 是 用 "url.keyword" 
作为 字段 名 。 当 你 还 对 分 词 字段 发 起 聚合 和 排序 请 求 的 时 候 ， 直 接 提示 无 法 构建 
fielddata 了 ! 


在 Logstash 5.0 中 ， 同 时 还 保留 携带 了 针对 Elasticsearch 2.x 的 template 文件 ， 
在 那里 ， 通 过 旧版 本 的 mapping 配置 ， 达 到 和 新 版 本 相同 的 行为 效果 : 对 应 统计 字 
段 明 确 设置 "index":"not analyzed","doc values":true ， 以 及 对 分 词 字段 
加 上 对 fielddata 49 {"format":"disabled"} ° 


e geo_point 


Elasticsearch 支持 geo point X?! > geo distance 聚合 等 等 。 比 如 说 ， 你 可 以 请 求 
某 geo point 点 方圆 10 千 米 内 数据 点 的 总 数 。 在 Kibana 的 tilemap 类 型 面板 
， 就 会 用 到 这 个 类 型 的 数据 。 


e half float 


Elasticsearch 5.0 新 引入 了 half float 类 型 。 比 标准 的 float 类 型 占用 更 少 的 资源 ， 
提供 更 好 的 性 能 。 在 明确 自己 数值 范围 较 小 的 时 候 可 用 。 刚 巧 ， 经 纬度 就 是 一 个 明 
确 的 数值 范围 很 小 的 数据 。 


其 他 模板 配置 建议 
e order 
如 果 你 有 自己 单独 定制 template 的 想法 ， 很 好 。 这 时 候 有 几 种 选择 : 


1. Æ logstash/outputs/elasticsearch 配置 中 开启 manage template => false 
选项 ， 然 后 一 切 自己 动手 ; 

2. Æ logstash/outputs/elasticsearch 配置 中 开启 template => 
"/path/to/your/tmpl.json" 选项 ， 让 logstash 来 发 送 你 自己 写 的 
template 文件 ; 

3. 避免 变更 logstash 里 的 配置 ， 而 是 另外 发 送 一 个 template ， 利 用 
elasticsearch 的 templates order 功能 。 


这 个 order 功能 ， 就 是 elasticsearch 在 创建 一 个 索引 的 时 候 ， 如 果 发 现 这 个 索引 同 
多 个 template ， 那 么 就 会 先 应 用 order 数值 小 的 template 设置 ， 然 后 
再 应 用 一 遍 order 数值 高 的 作为 覆盖 ， 最 终 达 到 一 个 merge 的 效果 。 


比如 ， 对 上 面 这 个 模板 已 经 很 满意 ， 只 想 修 改 一 下 refresh interval ， 那 么 只 
需要 新 写 一 个 


herder : 1, 

"template" : "logstash-*", 

"settings" : f 
"index.refresh_interval" : "20s" 


然后 运行 curl -XPUT http://localhost:9200/ template/template newid - 
d 'Q/path/to/your/tmpl.json' FPA ° 


日 


logstash 默认 的 模板 ，order 是 0，id 是 logstash， 通 过 
logstash/outputs/elasticsearch 的 配置 选项 template_name 修改 。 你 的 新 模板 就 


不 要 跟 这 个 名 字 冲 突 了 。 


& iX UB 44 (Email) 
配置 示例 


output { 
email { 
to => "admin@website.com, root@website.com" 
cc => "other@website.com" 
via => "smtp" 
subject => "Warning: %{title}" 
options => { 


smtpIporHost => "localhost", 
port SENSE 
domain -» 'localhost.localdomain', 
userName -» nil, 
password -» nil, 
authenticationType -» nil, £ (plain, login and cram. 
md5 ) 
starttls => true 
} 
htmlbody => "" 
body => "" 
attachments => ["/path/to/filename" | 
} 
} 


注意 : 以 上 示例 适用 于 Logstash 1.5 * options => 的 参数 配置 在 
Logstash 2.0 之 后 的 版 本 已 被 移 除 ， (126 邮箱 发 送 到 qq 邮箱 ) 示例 如 下 : 


output { 


email { 
port =o M25 
address => "smtp.126.com" 
username => "test@126.com" 
password => i 
authentication => "plain" 
use tls => true 
from => "test@126.com" 
subject => "Warning: %{title}" 
to => "test@qq.com" 
via => "smtp" 
body => "%{message}" 

} 


解释 


outputs/email 插件 支持 SMTP 协议 和 sendmail 两 种 方式 ， 通 过 via 参数 设置 。 
SMTP 方式 有 较 多 的 options 参数 可 配置 。sendmail 只 能 利用 本 机 上 的 sendmail 
服务 来 完成 一 一 文档 上 描述 了 Mail 库 支 持 的 sendmail 配置 参数 ， 但 实际 代码 中 
没有 相关 处 理 ， 不 要 被 迷惑 了 。。。 


调用 命令 执行 (Exec) 


outputs/exec 插件 的 运用 也 非常 简单 ， 如 下 所 示 ， 将 logstash 切割 成 的 内 容 作为 参 
数 传递 给 命令 。 这 样 ， 在 每 个 事件 到 达 该 插件 的 时 候 ， 都 会 触发 这 个 命令 的 执行 。 


output { 
exec { 
command => "sendsms.pl \"%{message}\" -t %{user}" 


需要 注意 的 是 。 这 种 方式 是 每 次 都 重新 开始 执行 一 次 命令 并 退出 。 本 身 是 比较 慢 速 
的 处 理 方式 (程序 加 载 ， 网 络 建 联 等 都 有 一 定 的 时 间 消 耗 )。 最 好 只 用 于 少量 的 信息 
处 理 场景 ， 比 如 不 适用 nagios 的 其 他 报警 方式 。 示 例 就 是 通过 短信 发 送 消息 。 


保存 成 文件 (File) 


通过 日 志 收 集 系统 将 分 散在 数 百 台 服务 器 上 的 数据 集中 存储 在 某 中 心服 务 器 上 ， 这 
是 运 维 最 原始 的 需求 。 早 年 的 scribed ， 其 至 直接 就 把 输出 的 语法 命名 为 
<store> 。Logstash 当然 也 能 做 到 这 点 。 


fe LogStash::Inputs::File 不 同 ，LogStash;: :Outputs::File 里 可 以 使 用 
sprintf format 格式 来 自动 定义 输出 到 带 日 期 命名 的 路 径 。 


配置 示例 


output { 
file { 
path => "/path/to/%{t+yyyy}/%{+MM}/%{+dd}/%{host}.log.gz" 
message_format => "%{message}" 
gzip => true 


解释 


使 用 output/file 插件 首先 需要 注意 的 就 是 message_format 参数。 插件 默认 是 输 
出 整个 event 的 JSON 形式 数据 的 。 这 可 能 跟 大 多 数 情况 下 使 用 者 的 期 望 不 符 。 大 
家 可 能 只 是 希望 按照 日 志 的 原始 格式 保存 就 好 了 。 所 以 需要 定义 为 96 

(message) ， 当 然 ， 前 提 是 在 之 前 的 filter 插件 中 ， 你 没有 使 用 remove field 
或 者 update 等 参数 删除 或 修改 %{message} 字段 的 内 容 。 


另 一 个 非常 有 用 的 参数 是 gzip。gzip 格式 是 一 个 非常 奇特 而 友好 的 格式 。 其 格式 包 
括 有 : 


e 10 字 节 的 头 ， 包 含 幻 数 、 版 本 号 以 及 时 间 稚 

e 可 选 的 扩展 头 ， 如 原文 件 名 

e 文件 体 ， 包 括 DEFLATE 压 缩 的 数据 

e 8 字 节 的 尾 注 ， 包 括 CRC-32 校 验 和 以 及 未 压缩 的 原始 数据 长 度 


这 样 gzip 就 可 以 一 段 一 段 的 识别 出 来 数据 — 反 过 来 说 ， 也 就 是 可 以 一 段 一 段 压 
缩 了 添加 在 后 面 ! 


这 对 于 我 们 流 式 添加 数据 简直 太 棒 了 ! 


小 贴 士 : 你 或 许 见 过 网 络 流传 的 parallel 命令 行 工 具 并 发 处 理 数据 的 神奇 文档 ， 但 
在 自己 用 的 时 候 总 见 不 到 效果 。 实 际 上 就 是 因为 : 文档 中 处 理 的 gzjp 文件 ， 可 以 分 
开 处 理 然后 再 合并 的 。 


1. 按照 Logstash 标准 ， 其 实 应 该 可 以 把 数据 格式 的 定义 改 在 codec 插件 中 完 
成 ， 但 是 logstash-output-file 插件 内 部 实现 中 跳 过 了 @codec.decode 这 
步 ， 所 以 codec o | 

2. 按照 Logstash 标准 ， 配 置 参 数 的 值 可 以 使 用 event sprintf 格式 。 但 是 
logstash-output-file mis event.sprintf(@path) 的 结果 ， 还 附加 了 一 

inside file root? 校 验 (个 人 猜测 是 为 了 防止 越权 到 其 他 路 径 )， 这 个 
file root 是 通过 直接 对 path AATA / 符号 得 到 的 。 如 果 在 sprintf 格 
AFRA / 符号 ， 、 分 后 的 结果 就 无 法 正确 解析 了 。 


所 以 ， 如 下 所 示 配 置 ， 虽 然 看 起 来 是 正确 的 ， 实 际 效果 却 不 对 ， 正 确 写 法 应 该 是 本 
节 之 前 的 配置 示例 那样 。 


output { 
file { 
path => "/path/to/%{+yyyy/MM/dd}/%{host}.log.gz" 
codec => line { 
format => "%{message}" 


报警 到 Nagios 


Logstash 中 有 两 个 output 插件 是 nagios A * %9 » outputs/nagios 插件 发 送 数 据 给 
本 机 的 nagios.cmd '"&iÉ4 4 3t outputs/nagios nsca 插件 则 是 调用 

send nsca 命令 以 NSCA 协议 格式 把 数据 发 送 给 nagios 服务 器 ( 远 端 或 者 本 地 器 
可 ) 。 


Nagios.Cmd 


nagios.cmd 是 nagios 服务 器 的 核心 组 件 。nagios 事件 处 理 和 内 外 交互 都 是 通过 这 
个 管道 文件 来 完成 的 。 


使 用 CMD 方式 ， 需 要 自己 保证 发 送 的 Logstash 事件 符合 nagios 事件 的 格式 。 即 
必须 在 filter 阶段 预先 准备 好 nagios_host 和 nagios service 字段 ; 此 外 ， 
如 果 在 filter 阶段 也 准备 好 nagios_annotation 和 nagios level 字段 ， 这 里 
也 会 自动 转换 成 nagios 事件 信息 。 


filter { 
if [message] =~ /err/ { 
mutate { 
add_tag => "nagios" 
rename => ["host", "nagios_host"] 
replace => ["nagios service", "logstash_check_%{type 
dex] 
} 
} 
} 
output { 
if "nagios" in [tags] { 
nagios { } 
j 
} 


如 果 不 打 算 在 filter 阶段 提供 nagios_level ， 那 么 也 可 以 在 该 插件 中 通过 参数 
配置 。 


所 谓 nagios level ， 即 我 们 通过 nagios plugin 检查 数据 时 的 返回 值 。 其 取 值 范 
围 和 含义 如 下 : 


e "0"， 代 表 "OK"， 服 务 正常 ; 

e. "1"， 代 表 "WARNNING"， 服 务 警告， 一 般 nagios plugin 命令 中 使 用 -w 参 
RAK B AA : 

e. "2"> KR "CRITICAL" > JÉ% * —AK nagios plugin 命令 中 使 用 -c 参数 
设置 该 阅 值 ; 

。"3"， 代 表 "UNKNOWN"， 未 知 状态 ， 一 般 会 在 timeout 等 情况 下 出 现 。 


默认 情况 下 ， 该 插件 会 以 "CRITICAL" 等 级 发 送 报警 给 Nagios 服务 器 。 


nagios.cmd 文件 的 具体 位 置 ， 可 以 使 用 command file 参数 设置 。 默 认 位 置 是 
"/var/lib/nagios3/rw/nagios.cmd" ° 


X T Fe nagios.cmd 交互 的 具体 协议 说 明 ， 有 兴趣 的 读者 请 阅读 Using external 
commands in Nagios 一 文 ， 这 是 《Learning Nagios 3.0》 书 中 内 容 节选 


NSCA 


NSCA 是 一 种 标准 的 nagios 分 布 式 扩展 协议 。 分 布 在 各 机 器 上 的 send nsca 3t 
程 主动 将 监控 数据 推送 给 远 端 Nagios 服务 器 的 NSCA 进程 。 
" 


4 Logstash J& nagios 服务 器 没有 在 同一 个 主机 上 运行 的 时 候 ， 就 只 能 通过 NSCA 
方式 来 发 送 报警 了 一 一 当然 也 必须 在 Logstash 服务 器 上 安装 send nsca 命 
A o 


nagios 事件 所 需要 的 几 个 属性 在 上 一 段 中 已 经 有 过 描述 。 不 过 在 使 用 这 个 插件 的 时 
候 ， 不 要 求 提 前 准备 好 ， 而 是 可 以 在 该 插件 内 部 定义 参数 : 


output { 
nagios_nsca { 
nagios_host => "%{host}" 
nagios_service => "logstash_check_%{type}" 
nagios_status => "2" 
message_format => "%{@timestamp}: %{message}" 
host => "nagiosserver .domain.com" 


这 里 请 注意 ， host 和 nagios host 两 个 参数 ， 分 别 是 用 来 设置 nagios 服务 
器 的 地 址 ， 和 报警 信息 中 有 问题 的 服务 器 地 址 。 


关于 NSCA 原理 ， 架 构 和 配置 说 明 ， 还 不 了 解 的 读者 请 阅读 官方 网 站 Using 
NSClient++ from nagios with NSCA 一 节 。 


> Ar ys ` 
推荐 阅读 
除了 nagios 以 外 ，logstash 同样 可 以 发 送信 息 给 其 他 常见 监控 系统 。 方 式 和 
nagios 大 同 小 异 : 

e outputs/ganglia 插件 通过 UDP 协议 ， 发 送 gmetric 型 数据 给 本 机 / 远 端的 


gmond 或 者 gmetad 
e outputs/zabbix 插件 调用 本 机 的 zabbix_sender 命令 发 送 


输出 到 Statsd 


基础 知识 


Statsd 最 早 是 2008 年 Flickr 公司 用 Perl 写 的 针对 Graphite、datadog 等 监控 数据 
后 端 存 储 开 发 的 前 端 网 络 应 用 ，2011 年 Etsy 公司 用 node.js 重 构 。 用 于 接收 (默认 
UDP)、 写 入 、 读 取 和 聚合 时 间 序 列 数据 ， 包 括 即 时 值 和 累积 值 等 。 


Graphite 是 用 Python 模仿 RRDtools 写 的 时 间 序 列 数据 库 套 件 。 和 包括 三 个 部 分 : 


e carbon: 是 一 个 Twisted 守 护 进 程 ， 监 听 处 理 数据 ; 
e whisper: 存储 时 间 序 列 的 数据 库 ; 
e webapp: 一 个 用 Django 框架 实现 的 网 页 应 用 。 


Graphite 安装 简介 
过 如 下 几 步 安装 Graphite : 


E 


1. 4 & cairo 和 pycairo 库 


# yum -y install cairo pycairo 


du AME 


1. pip 3X 
# yum install python-devel python-pip 


# pip install django django-tagging carbon whisper graphite-web 
uwsgi 


1. 配置 Graphite 


# cd /opt/graphite/webapp/graphite 
# cp local_settings.py.example local_settings.py 
# python manage.py syncdb 


修改 local settings.py 中 的 DATABASE 为 设置 的 db 信息 。 


1. 启动 cabon 


cd /opt/graphite/conf/ 
cp carbon.conf.example carbon.conf 


# 
# 
# cp storage-schemas.conf.example storage-schemas.conf 
# cd /opt/graphite/ 

# 


./bin/carbon-cache.py start 


statsd 安装 简介 


1. Graphite 地 址 设置 


# cd /opt/ 

# git clone git://github.com/etsy/statsd.git 
# cd /opt/statsd 

# cp exampleConfig.js Config.js 


根据 Graphite 服务 器 地 址 ， 修 改 Config.js 中 的 配置 如 下 : 


graphitePort: 2003, 

graphiteHost: "10.10.10.124", 

port: 8125, 

backends: [ "./backends/graphite" ] 


1. uwsgi 配置 


cd /opt/graphite/webapp/graphite 
cat > wsgi_graphite.xml <<EOF 
<uwsgi> 
<socket>0.0.0.0:8630</socket> 
<workers>2</workers> 
<processes>2</processes> 
<listen>100</listen> 
<chdir>/opt/graphite/webapp/graphite</chdir> 
<pythonpath>. .</pythonpath> 
<module>wsgi</module> 
<pidfile>graphite.pid</pidfile> 
<master>true</master> 
<enable-threads>true</enable-threads> 
<logdate>true</logdate> 
<daemonize>/var/log/uwsgi_graphite.1log</daemonize> 
</uwsgi> 
EOF 
cp /opt/graphite/conf/graphite.wsgi /opt/graphite/webapp/graphit 
e/wsgi.py 


1. nginx 的 uwsgi 配置 


cat > /usr/local/nginx/conf/conf.d/graphite.conf ««EOF 
server { 

listen 8081; 

server_name graphite; 


access log /opt/graphite/storage/log/webapp/access.log ; 
error log /opt/graphite/storage/log/webapp/error.log ; 


location / ( 
uwsgi pass 0.0.0.0:8630; 
include uwsgi params; 
proxy connect timeout 300; 
proxy send timeout 300; 
proxy read timeout 300; 


4 uwsgi -x /opt/graphite/webapp/graphite/wsgi graphite. xml 
4 systemctl nginx reload 


1. 数据 测试 
echo "test.logstash.num:100|c" | nc -w 1 -u $IP $port 


如 果 安 装配 置 是 正常 的 ， 在 graphite 的 堪 侧 metrics->stats->test->logstash->num 的 
表 ，statsd 里 面 多 了 numStats 等 数据 。 


配置 示例 


output { 
statsd { 
host => "statsdserver.domain.com" 
namespace => "logstash" 
sender => "%{host}" 
increment => ["httpd.response.%{status}"] 


解释 


Graphite 以 树 状 结构 存储 监控 数据 ， 所 以 statsd 也 是 如 此 。 所 以 发 送 给 statsd 的 
数据 的 key 也 一 定 得 是 "first.second.tree.four" 这 样 的 形式 。 而 在 logstash-output- 
statsd 插件 中 ， 就 会 以 三 个 配置 参数 来 拼接 成 这 种 形式 : 


namespace.sender.metric 


其 中 namespace 和 sender 都 是 直接 设置 的 ， 而 metric 又 分 为 好 几 个 不 同 的 参数 
可 以 分 别 设 置 。statsd 支持 的 metric 类 型 如 下 : 


metric 类 型 


e increment 增 量 ， 一 个 计量 周期 内 ， 某 个 数字 接收 了 多 少 次 ， 比 如 nginx 的 
status 状态 码 。 


示例 语法 : increment => ["nginx.status.%{status}"] 
e decrement 
语法 同 increment 。 


e count 对 数字 的 计数 ， 比 如 ， 每 秒 接收 一 个 数字 ， 一 个 计量 周期 内 ， 所 有 数字 
的 和 ， 比 如 nginx 的 body. bytes sent ^ 


示例 语法 : count => {"nginx.bytes" => "%{bytes}"} 


e gauge 


语法 同 count ° 
e Set 
语法 同 count ° 


e timing 时 间 范 围 内 ， 某 种 数字 的 最 大 值 ， 最 小 值 ， 平 均值 ， 比 如 nginx 的 响应 
时 间 request time ° 


语法 同 count ° 


关于 这 些 metric 类 型 的 详细 说 明 ， 请 阅读 statsd 文 
档 : https://github.com/etsy/statsd/blob/master/docs/metric_types.md ° 


推荐 阅读 


e Etsy 发 布 nodejs 版 本 statsd 的 博客 : Measure Anything, Measure 
Everything 
e Flickr 发 布 statsd 的 博客 : Counting & Timing 


标准 输出 (Stdout) 


和 之 前 inputs/stdin 插件 一 样 ，outputs/stdout 插件 也 是 最 基础 和 简单 的 输出 插件 。 
同样 在 这 里 简单 介绍 一 下 ， 作 为 输出 插件 的 一 个 共性 了 解 。 


配置 示例 


output { 
stdout { 
codec => rubydebug 
workers => 2 


解释 
输出 插件 统一 具有 一 个 参数 是 workers 。Logstash 为 输出 做 了 多 线程 的 准备 。 


其 次 是 codec 设置 。codec 的 作用 在 之 前 已 经 讲 过 。 可 能 除了 
codecs/multiline ， 其 他 codec 插件 本 身 并 没有 太 多 的 设置 项 。 所 以 一 般 省 略 
掉 后 面 的 配置 区 段 。 换 和 句 话 说。 上 面 配置 示例 的 完全 写法 应 该 是 : 


output { 
stdout { 
codec => rubydebug { 
} 


workers => 2 


单 就 outputs/stdout 插件 来 说 ， 其 最 重要 和 常见 的 用 所 以 在 不 太 有 效 
的 时 候 ， 加 上 命令 行 参数 -vv 运行 ， 查 看 更 多 详细 调试 信 ， 
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发 送 关 网 络 数据 (TCP) 


虽然 之 前 我 们 已 经 提 到 过 不 建议 直接 使 用 LogStash::Inputs::TCP 和 
LogStash::Outputs::TCP 做 转发 工作 ， 不 过 在 实际 交流 中 ， 发 现 确实 有 不 少 朋友 觉 
得 这 种 简单 配置 足够 使 用 ， 因 而 不 愿意 多 加 一 层 消 息 队 列 的 。 所 以 ， 还 是 把 
Logstash 如 何 直 接 发 送 TCP 数据 也 稍微 提 点 一 下 。 


配置 示例 


output { 


tcp { 
host => "192.168.0.2" 


port => 8888 
codec => json_lines 


配置 说 明 


在 收集 端 采 用 top 方式 发 送 给 远 端的 top 端口 。 这 里 需要 注意 的 是 ， 默 认 的 codec 
选项 是 json。 而 远 端的 LogStash::Inputs::TCP 的 默认 codec 选项 却 是 line ! 所 
以 不 指定 各 自 的 codec ， 对 接 肯 定 是 失败 的 。 


另外 ， 由 于 IO BUFFER 的 原因 ， 即 使 是 两 端 共 同 约定 为 json 依然 无 法 正常 运行 ， 
接收 端 会 认为 一 行 数据 没 结 束 ， 一 直 等 待 直至 自己 OutOfMemory ! 

所 以 ， 正 确 的 做 法 是 ， 发 送 端 指定 codec 为 json_lines ， 这 样 每 条 数据 后 面 会 加 
上 一 个 回 车 ， 接 收 端 指定 codec 为 json lines 或 者 json 均 可 ， 这 样 才能 正常 处 
F 。 包 括 在 收集 端 已 经 切割 好 的 字段 ， 也 可 以 直接 带 入 收集 端 使 用 了 。 


HDFS 


e https://github.com/dstore-dbap/logstash-webhdfs 


This plugin based on WebHDFS api of Hadoop, it just POST data to WebHDFS 
port. So, it's a native Ruby code. 


output { 
hadoop_webhdfs { 

workers => 2 

server => "your.nameno.de:14000" 

user => "flume" 

path => "/user/flume/logstash/dt=%{+Y } -%{+M}-%{+d}/logst 
ash-9?6(*H) . log" 

flush size -» 500 

compress -» "snappy" 

idle flush time -» 10 

retry interval -» 0.5 


e https://github.com/avishai-ish-shalom/logstash-hdfs 


This plugin based on HDFS api of Hadoop, it import java classes like 
org.apache.hadoop.fs.FileSystem etc. 


Configuration 


output { 
hdfs ( 
path -» "/path/to/output file.log" 
enable append -» true 


Howto run 


CLASSPATH-$(find /path/to/hadoop -name '*.jar' | tr '\n' ':'):/e 
tc/hadoop/conf:/path/to/logstash-1.1.7-monolithic.jar java logst 
ash.runner agent -f conf/hdfs-output.conf -p /path/to/cloned/log 
stash-hdfs 


场景 示例 


前 面 虽然 介绍 了 几 十 个 常用 的 Logstash 插件 的 常见 配置 项 。 但 是 过 多 的 选择 下 ， 
如 何 组 合 使 用 这 些 插 件 ， RRA HERA RT A 些 最 常见 的 
日 志 场 景 ， 演 示 一 下 针对 性 的 组 件 搭配 。 和 希望 能 给 读者 带 来 一 点 局 发 


Nginx 访问 日 志 


grok 
Logstash 默认 自 带 了 apache 标准 日 志 的 grok 正则 : 


COMMONAPACHELOG %{IPORHOST:clientip} %{USER:ident} %{NOTSPACE: au 
th} \[%{HTTPDATE:timestamp}\] "(?:%{WORD:verb} %{NOTSPACE:reques 
t}(?: HTTP/%{NUMBER:httpversion})?|%{DATA:rawrequest})" %{NUMBER 
: response} (?:%{NUMBER:bytes}|-) 

COMBINEDAPACHELOG %{COMMONAPACHELOG} %{QS:referrer} %{QS:agent} 


对 于 nginx 标准 日 志 格式 ， 可 以 发 现 只 是 最 后 多 了 一 个 
$http x forwarded for 变量 。 所 以 nginx 标准 日 志 的 grok 正则 定义 是 : 


MAINNGINXLOG %{COMBINEDAPACHELOG} %{QS:x_forwarded_for} 


自 定 义 的 日 志 格 式 ， 可 以 照 此 修改 。 


split 


nginx 日 志 因 为 部 分 变量 中 内 含 空格 ， 所 以 很 多 时 候 只 能 使 用 %{QS} 正则 来 做 分 
割 ， 性 能 和 细 度 都 不 太 好 。 如 果 能 自 定 义 一 个 比较 少见 的 字符 作为 分 隔 符 ， 那 么 处 
理 起 来 就 简单 多 了 。 假 设 定义 的 日 志 格 式 如 下 : 


log_format main "$http_x_forwarded_for | $time_local | $request 
| $status | $body_bytes_sent | " 

"$request_body | $content_length | $http_referer 
| $http_user_agent | $nuid | " 
"$http_cookie | $remote_addr | $hostname | $upst 


ream_addr | $upstream_response_time | $request_time"; 


nginx 访 问 日 志 


117.136.9.248 | 08/Apr/2015:16:00:01 +0800 | POST /notice/newmessage? 
sign=cba4f614e05db285850cadc696fcdad0&token=JAGQ92Mjs3-- 

gik b DsPIQHcyMKY GpD&did=4b749736ac70f12df700b18cd6d051d5&o0sn= 
android&osv=4.0.4&appv=3.0.1&net=460-02- 
2g&longitude=120.393006&latitude=36. 178329&ch=360&lp=1 &ver=1 &ts=142 
8479998151 &im=869736012353958&sw=0&sh=08&la=zh- 
CN&lm=weixin&dt=vivoS11t HTTP/1.1 | 200 | 132 | abcd-sign- 
v1://ddO3c57f8cb6fcef919ab5df66f2903f:d51asq5yslwnyz5t/[x22typeWw22:4, x 
22uid\x22:7567306} | 89 | - | abcd/3.0.1, Android/4.0.4, vivo S11t | 
nuidZ0C0A0A0A01E02455EA7CF47E02FD072C1428480001.157 |- | 
10.10.10.13 | bnx02.abcdprivate.com | 10.10.10.22:9999 | 0.022 | 0.022 
59.50.44.53 | 08/Apr/2015:16:00:01 +0800 | POST /feed/pubList? 
appv=3.0.3&did=89da72550de488328e2aba5d97 850e9f&dt=iPhone6%2C2&i 
m=B48C21F3-487E-4071-9742- 
DC6D61710888&la=cn&latitude=0.000000&lm=weixin&longitude=0.0000008! 
p=-1.000000&net=0-0- 
wifi&osn=iOS&osv=8.1.3&Sh=568.000000&sw=320.000000&token=7NobA7a 
sg3Jb6n904ETdPXyNNiHwMs4J&ts=1428480001275 HTTP/1.1 | 200 | 983 | 
abcd-sign- 
v1://0398870a0b25b29aae65cd553addc43d:72214ee85d7cca22/{\x22nextke 
W\x22\x22\x22 \x22uid\x22:\x2213062545\x22,\x22token\x22:\x227NobA7asg 
3Jb6n904ETdPXyNNiHwMs4J\x22} | 139 | - | Shopping/3.0.3 (iPhone; iOS 
8.1.3; Scale/2.00) | 
nuid=OCOA0A0A81DF2455017D548502E48E2E1428480001.154 | 
nuid=CgoKDFUk34GFVHOBLo7kAg== | 10.10.10.11 | bnx02.abcdprivate.com 
| 10.10.10.35:9999 | 0.025 | 0.026 


然后 还 可 以 针对 request 做 更 细致 的 切 分 。 比 如 URL 参数 部 分 。 很 明显 ，URL 参 
数 中 的 字段 ， 顺 序 是 乱 的 ， 第 一 行 ， 问 号 之 后 的 第 一 个 字段 是 sign， 第 二 行 问号 之 
后 的 第 一 个 字段 是 appv， 所 以 需要 将 字段 进行 切 分 ， 取 出 每 个 字段 对 应 的 值 。 官 
方 自 带 grok 满足 不 了 要 求 。 最 终 采 用 的 logstash 配置 如 下 : 


filter { 
ruby { 
init => "@kname = ['http_x_forwarded_for', 'time_local', ' 
request', 'status', 'body_bytes_sent', 'request_body', 'content_leng 
th', 'http_referer', 'http_user_agent', 'nuid', 'http_cookie', 'remot 
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e_addr', 'hostname', 'upstream_addr', 'upstream_response_time', 'req 
uest_time']" 
code => " 
new event = LogStash: :Event.new(Hash[@kname.zip(even 
t.get('message').split('|'))]) 
new event.remove('Qtimestamp') 
event.append(new event) 


j 
if [request] ( 
ruby { 
init => "Qkname = ['method', 'uri', 'verb']" 
code => " 
new event = LogStash::Event.new(Hash[Qkname.zip( 
event.get('request').split(' '))]) 
new event.remove('Qtimestamp') 
event.append(new event) 


} 
if [uri] { 
ruby { 
init => "@kname = ['url_path', 'url_args']" 
code => " 


new event = LogStash: :Event.new(Hash[@kname. 

Zip(event.get('uri').split('?'))]) 
new_event.remove('@timestamp' ) 
event.append(new event) 


j 
kv { 
prefix => "url " 
source -» "url args" 
field split -» "& " 
remove field => [ "url args","uri","request" ] 
j 
j 
j 
mutate { 


convert => [ 
"body bytes sent" , "integer", 


"content length", "integer", 
"upstream response time", "float", 
"request time", "float" 


j 
date { 
match => [ "time local", "dd/MMM/yyyy:hh:mm:ss Z" ] 
locale -» "en" 
j 
} 
终结 果 : 


"message" => "1.43.3.188 | 08/Apr/2015:16:00: 
01 +0800 | POST /search/suggest?appv=3.0.3&did=dfd5629d705d40079 
5f698055806f01d&dt-iPhone79622C2&im-AC926907 -27AA-4A10-9916-C5DC75 
F29399&la-cn&latitude--33.903867&1m-sina&longitude-151.208137&1lp 
--1.000000&net-0-0-wifi&osn-iOS&osv-8.1.3&sh-667.000000&sw-375.0 
00000&token=_ovaPz6Ue68ybBuhXustPbG- xfiwbsPO&ts=1428480001567 HT 
TP/1.1 | 200 | 353 | abcd-sign-v1://a24b478486d3bb92ed89a901541b 
60a5:b23e9d2c14fe6755/(NNx22keyNNx22:NNX221astNNx22, \\x220ffset\ 
NX22:NNX220NNX22, NNX22tokenNNx22:NNx22 ovaPz6Ue68ybBuhXustPbG - xf 
1WbsPONNx22, \\x221imit\\x22:\\x2220\\x22} | 148 | - | abcdShoppi 
ng/3.0.3 (iPhone; iOS 8.1.3; Scale/2.00) | nuid-0B0A0A0A9A64AF54 
F97634640230944E1428480001.113 | nuid=CgoKCiSvZJpkNHb5TpQwAg== | 
10.10.10.11 | bnx02.abcdprivate.com | 10.10.10.26:9999 | 0.070 
| 0.071", 
"Qversion" => "1", 
"Qtimestamp" => "2015-04-08T08:00:01.000Z", 
"type" => "nginxapiaccess", 
"host" => "blog05.abcdprivate.com", 
"path" => "/home/nginx/logs/api.access.log 


"http x forwarded for" => "1.43.3.188", 
"time local" => " 08/Apr/2015:16:00:01 +0800", 
"status" => "200", 
"body_bytes_sent" => 353, 
"request_body" => "abcd-sign-v1://a24b478486d3bb92 


ed89a901541b60a5:b23e9d2c14fe6755/(NNx22keyNNx22:NNX221astNNx22, 
\\x220f f SetENNX22:NNX220NNX22, \\x22token\\x22:\\x22_ovaPz6Ue68ybB 
uhXustPbG-xfiWbsPONNx22, \\x221Limit\\x22:\\x2220\\x22}", 


"content length" => 


"http referer" => 
"http user agent" => 
8.1.3; Scale/2.00)", 
"nuid" => 
30944E1428480001.113", 
"http cookie" => 
"remote addr" => 
"hostname" => 
"upstream_addr" => 
"upstream_response_time" => 
"request_time" => 
"method" => 
"verb" => 
"url path" => 
"url appv" => 
"url did" => 
d", 
"url dt" => 
"url im" => 
29399", 
"url la" => 
"url latitude" => 
"url lm" => 
"url longitude" => 
"url lp" => 
"url net" => 
"url osn" => 
"url osv" => 
"url sh" => 
"url sw" => 
"url token" => 
o", 
"url ts" => 


"abcdShopping/3.0.3 (iPhone; iOS 


"nuid-0B0A0A0A9A64AF54F976346402 


"nuid-zCgoKCi1SvZJpkNHb5TpQwAg--", 
"10.10.10.11", 
"bnx02.abcdprivate.com", 
"10.10.10.26:9999", 

0.070, 

0.071, 

"POST", 

"HTTP/1.1", 

"/search/suggest", 

Bee 
"dfd5629d705d400795f698055806f01 


"7Phone7%2C2", 
"AC926907 -27AA- 4A10 -9916-C5DC75F 


senu 
"-33.903867", 
"sina", 
"151.208137", 
"-1.000000", 
"Q-0-wifi", 
POS 
nepos 
"667.000000", 
"375.000000", 
"_ovaPz6Ue68ybBuhXustPbG-xf1WbsP 


"1428480001567" 


如 果 url 参数 过 多 ， 可 以 不 使 用 kv 切割 ， 或 者 预先 定义 成 nested object 后 ， 改 成 
数组 形式 : 


if [uri] { 
ruby { 
init => "@kname = ['url_path', 'url_args']" 
code => " 


new event = LogStash::Event.new(Hash[Qkname. 


zip(event.get('request').split('?'))]) 
new event.remove('Qtimestamp') 
event.append(new event) 


j 
if [url args] { 
ruby { 
init -» "Qkname - ['key','value']" 
code -» "event.set('nested args', event.get( 
'url args').split('&').collect {|i| Hash[Qkname.zip(i.split('-') 


pa? 


remove field => [ "url_args", "uri", "request" 


采用 nested object 的 优化 原理 和 nested object 的 使 用 方式 ， 请 阅读 稍 后 


Elasticsearch 调 优 章节 。 


json format 


自 定义 分 隔 符 虽 好 ， 但 是 配置 写 起 来 毕 竞 复杂 很 多 。 其 实 对 logstash 来 说 ，nginx 
日 志 还 有 另 一 种 更 简便 的 处 理 方式 。 就 是 自 定 义 日 志 格 式 时 ， 通 过 手工 拼写 ， 直 接 
输出 成 JSON 格式 : 


log format json '{"@timestamp":"$time_iso8601", ' 
host": "Sserver_addr",.” 
'""clientip":"$remote addr",' 
'""size":$body bytes sent," 
'""responsetime":$request time, ' 
'"upstreamtime":"$upstream response time", ' 
'"upstreamhost":"$upstream addr", ' 
'"http_host":"$host", ' 
ie eh SIT S 
""xff":"$http x forwarded for", ' 
'""referer":"$http referer",' 
'"agent":"$http user agent", ' 
' "status" :"$status",'; 


然后 采用 下 面 的 logstash 配置 即 可 : 


input { 
file { 
path => "/var/1log/nginx/access.log" 
codec => json 


j 
j 
filter ( 
mutate { 
split => [ "upstreamtime", "," | 
j 
mutate { 
convert => [ "upstreamtime", "float" ] 
j 
j 


这 里 采用 多 个 mutate 464+ > AA upstreamtime 可 能 有 多 个 数值 ， 所 以 先 切割 成 数 
组 以 后 ， 再 分 别 转换 成 浮 点 型 数值 。 而 在 mutate 中 ，convert 函数 执行 优先 级 高 于 
split 函数 ， 所 以 只 能 分 开 两 步 写 。mutate 内 各 函数 优先 级 顺序 ， 之 前 插件 介绍 章节 
有 详细 说 明 ， 读 者 可 以 返回 去 加 强 阅 读 。 


syslog 


Nginx 从 1.7 版 开始 ， 加 入 了 syslog 支持 。Tengine 则 更 早 。 这 样 我 们 可 以 通过 
syslog 直接 发 送 日 志 出 来 。Nginx 上 的 配置 如 下 : 


access log syslog:server-unix:/data0/rsyslog/nginx.sock locallog 


, 


或 者 直接 发 送 给 远程 logstash 机 器 : 


access log syslog:server=192.168.0.2:5140, facility=local6, tag=ng 
inx_access, severity=info logstashlog; 


默认 情况 下 ，Nginx 将 使 用 local7.info 等 级 ， nginx 为 标签 ， 发 送 数据 。 注 
意 ， 采 用 syslog 发 送 日 志 的 时 候 ， 无 法 配置 buffer=16k 选项 。 


Nginx 错误 日 志 


ais 错误 日 志 是 运 维 人 员 最 常见 但 又 极其 容易 忽略 的 日 eos o Nginx 错误 
& Rp AUR R d 个 隔 符 ， 也 没有 特别 方便 的 正则 模式 ， 但 通过 logstash 不 同 

E 的 组 合 ， 还 是 可 以 轻松 做 到 数据 处 理 。 

值得 注意 的 是 ，Nginx 错误 日 志 中 ， 有 一 类 数据 是 接收 过 大 请 求 体 时 的 报错 ， 默 认 

言 息 会 把 请 求 体 的 具体 字 节 数 记 录 下 来 。 每 次 请 求 的 字 节 数 基 本 都 是 在 变化 的 ， 这 

意味 着 常用 的 topN 等 聚合 函数 对 该 字段 都 没有 明显 效果 。 所 以 ， 对 此 需要 做 一 下 

特殊 处 理 。 


最 后 形成 的 logstash 配置 如 下 所 示 : 


filter { 
grok { 
match => { "message" => "(?<datetime>\d\d\d\d/\d\d/\d\d 
\d\d:\d\d:\d\d) \[(?<errtype>\w+)\] \S+: \*\d+ (?<errmsg>[4, ]+), 
(?<errinfo>.*)$" } 
} 
mutate { 
rename => [ "host", "fromhost" ] 
gsub => [ "errmsg", "too large body: \d+ bytes", "too la 
rge body" ] 


} 
if [errinfo] 
{ 
ruby { 
code => " 


new event = LogStash::Event.new(Hash[event.get(' 
errinfo').split(', ')-map{|1]| l.split(': ')}]) 

new event.remove('Qtimestamp') 

event.append(new event) 


j 
grok { 
match => { "request" => '"%{WORD: verb} %{URIPATH:urlpath 
}(?7:\?%{NGX_URIPARAM: urlparam})?(?: HTTP/%{NUMBER: httpversion})" 
Drs 
patterns dir -» ["/etc/logstash/patterns"] 
remove field -» [ "message", "errinfo", "request" ] 


2% xt 34 Ft logstash 配置 的 Nginx 错误 日 志 生 成 的 事件 如 下 所 示 : 


"@version": "1", 

"Qtimestamp": "2015-07-02T01:26:40.000Z", 

"type": "nginx-error", 

"errtype": "error", 

"errmsg": "client intended to send too large body", 
"fromhost": "webO033.mweibo.yf.sinanode.com", 

Vel T6nmbus 9 26:102 7)75 

"server": "api.v5.weibo.cn", 

"host": "\"api.weibo.cn\"", 


"verb": "POST", 

"urlpath": "/2/client/addlog_batch", 

"urlparam": "gsid- 2A254UNaSDeTXxGeRI7FMX9CrEyj21HXVZRG1arDV6 
PUJbrdANLROskWp9bXakjUZM5792FW9A5S9EU4jxqQ..&wm-3333 2001&i-0c6f 
156&b-1&from-1053093010&c-iphone&v p-21&skin-default&v f-1&s-8f1 
4e573&lang-zh CN&ua-iPhone7,1 weibo 5.3.0 iphone os8.3", 

"httpversion": "1.1" 


postfix A & 


postfix 是 Linux 平台 上 最 常用 的 邮件 服务 器 软件 。 邮 件 服 务 的 运 维 复杂 度 一 向 较 
高 ， 在 此 提供 一 个 针对 postfix 日 志 的 解析 处 理 方案 。 方 案 出 
自 ; https://github.com/whyscream/postfix-grok-patterns ° 


A postfix 默认 通过 syslog 方式 输出 日 志 ， 所 以 可 以 选择 通过 rsyslog 直接 转发 
给 logstash > 3, T Z4 dà logstash 读 取 rsyslog 记录 的 文件 。 下 列 配置 中 省 略 了 对 
syslog 协议 解析 的 部 分 。 


filter 1 
# grok log lines by program name (listed alpabetically) 
if [program] =~ /Apostfix.*\/anvil$/ { 


grok { 
patterns_dir => ["/etc/logstash/patterns.d"] 
match => [ "message", "%{POSTFIX_ANVIL}" ] 
tag_on_failure => [ "_grok_postfix_anvil_nomatch" ] 
add_tag => [ "_grok_postfix_success" ] 
} 
} else if [program] =~ /Apostfix.*\/bounce$/ { 
grok { 
patterns_dir => ["/etc/logstash/patterns.d"] 
match => [ "message", "%{POSTFIX_BOUNCE}" ] 
tag on failure => [ " grok postfix bounce nomatch" ] 
add tag => [ " grok postfix success" | 
} 
} else if [program] =~ /Apostfix.*\/cleanup$/ { 
grok { 
patterns_dir => ["/etc/logstash/patterns.d"] 
match => [ "message", "%{POSTFIX_CLEANUP}" 
l 
tag on failure -» [ " grok postfix cleanup nomatch" 
l 
add tag => [ " grok postfix success" | 
J 
) else if [program] =~ /Apostfix.*\/dnsblog$/ { 
grok { 


patterns_dir => ["/etc/logstash/patterns.d"] 


} 


match 


tag_on_failure 


add_tag 


else if [program] =~ 


grok { 


} 


patterns_dir 
match 
tag_on_failure 
add_tag 


else if [program] =~ 


grok { 


} 


patterns_dir 
match 
tag_on_failure 
add_tag 


else if [program] =~ 


grok { 


} 


patterns_dir 
match 
tag_on_failure 
add_tag 


else if [program] =~ 


grok { 


} 


patterns_dir 
match 
tag_on_failure 
add_tag 


else if [program] =~ 


grok { 


patterns_dir 
match 


tag_on_failure 


=> [ "message", "%{POSTFIX_DNSBLOG}" 


=> [ "_grok_postfix_dnsblog_nomatch" 


=> [ "_grok_postfix_success" ] 


/^postfix.*\/local$/ { 


=> ["/etc/logstash/patterns.d"] 
=> [ "message", "%{POSTFIX_LOCAL}" ] 
=> [ "_grok_postfix_local_nomatch" ] 
=> [ "_grok_postfix_success" ] 


/\postfix.*\/master$/ { 


=> ["/etc/logstash/patterns.d" ] 
=> [ "message", "%{POSTFIX_MASTER}" ] 
=> [ "_grok_postfix_master_nomatch" ] 
=> [ "_grok_postfix_success" ] 


/\postfix.*\/pickup$/ ( 


=> ["/etc/logstash/patterns.d"] 
=> [ "message", "%{POSTFIX_PICKUP}" ] 
=> [ "_grok_postfix_pickup_nomatch" ] 
=> [ "_grok_postfix_success" ] 


/^postfix.*NM/pipe$/ { 

=> ["/etc/logstash/patterns.d"] 

=> [ "message", "%{POSTFIX_PIPE}" ] 
=> [" grok postfix pipe nomatch" | 
=> [ " grok postfix success" ] 


/^postfix.*N/postdrop$/ { 


=> ["/etc/logstash/patterns.d"] 


=> [ "message", "%{POSTFIX_POSTDROP}" 


=> [ "_grok_postfix_postdrop_nomatch" 


eval 


h" ] 


add_tag 
} 
} else if [program] =~ 
grok { 
patterns_dir 
match 


tag_on_failure 


add_tag 
} 
} else if [program] =~ 
grok { 
patterns_dir 
match 
tag_on_failure 
add_tag 
} 
} else if [program] =~ 
grok { 
patterns_dir 
match 
tag_on_failure 
add_tag 
} 
} else if [program] =~ 
grok { 
patterns_dir 
match 


tag_on_failure 


add_tag 
} 
} else if [program] =~ 
grok { 
patterns_dir 
match 
tag_on_failure 


=> [ "_grok_postfix_success" ] 


/\postfix.*\/postscreen$/ { 


=> ["/etc/logstash/patterns.d"] 
=> [ "message", "%{POSTFIX_POSTSCREEN 


=> [ "_grok_postfix_postscreen_nomatc 
=> [ "_grok_postfix_success" ] 
/^postfix.*N/qmgr$/ { 

=> ["/etc/logstash/patterns.d"] 

=> [ "message", "%{POSTFIX_QMGR}" ] 
=> [ "_grok_postfix_qmgr_nomatch" ] 
=> [ "_grok_postfix_success" ] 
/postfix.*\/scache$/ { 

=> ["/etc/logstash/patterns.d"] 

=> [ "message", "%{POSTFIX_SCACHE}" ] 
=> [ "_grok_postfix_scache_nomatch" ] 
=> [ "_grok_postfix_success" ] 


/^postfix.*N/sendmail$/ { 


=> ["/etc/logstash/patterns.d" ] 
=> [ "message", "%{POSTFIX_SENDMAIL}" 


=> [ "_grok_postfix_sendmail_nomatch" 
=> [ "_grok_postfix_success" ] 
/^postfix.*N/smtp$/ { 

=> ["/etc/logstash/patterns.d"] 


=> [ "message", "%{POSTFIX_SMTP}" ] 
=> [ "_grok_postfix_smtp_nomatch" ] 


} 


add_tag 


} else if [program] =~ 


grok { 


} 


patterns_dir 
match 
tag_on_failure 
add_tag 


} else if [program] =~ 


grok { 


} 


patterns_dir 
match 
tag_on_failure 
add_tag 


} else if [program] =~ 


grok { 


} 


patterns_dir 
match 
tag_on_failure 
add_tag 


} else if [program] =~ 


grok { 


patterns_dir 
match 


tag_on_failure 


add_tag 


} else if [program] =~ 


grok { 


] 

] 
} 
WRITE}" ] 
omatch" ] 


patterns_dir 
match 


tag_on_failure 


add_tag 


=> [ "_grok_postfix_success" ] 
/^postfix.*\/lmtp$/ { 

=> ["/etc/logstash/patterns.d"] 

=> [ "message", "%{POSTFIX_LMTP}" ] 
=> [ "_grok_postfix_lmtp_nomatch" ] 
=> [ "_grok_postfix_success" ] 
/^postfix.*\/smtpd$/ { 

=> ["/etc/logstash/patterns.d"] 

=> [ "message", "%{POSTFIX_SMTPD}" ] 
=> [ "_grok_postfix_smtpd_nomatch" ] 
=> [ "_grok_postfix_success" ] 
/^postfix.*\/tlsmgr$/ { 

=> ["/etc/logstash/patterns.d"] 

=> [ "message", "%{POSTFIX_TLSMGR}" ] 
=> [ "_grok_postfix_tlsmgr_nomatch" ] 
=> [ "_grok_postfix_success" ] 


/^postfix.*\/tlsproxy$/ { 


=> ["/etc/logstash/patterns.d"] 
=> [ "message", "%{POSTFIX_TLSPROXY}" 


=> [ "_grok_postfix_tlsproxy_nomatch" 


=> [ "_grok_postfix_success" ] 


/^postfix.*M/trivial-rewrite$/ { 


=> ["/etc/logstash/patterns.d" ] 
=> [ "message", "%{POSTFIX_TRIVIAL_RE 


=> [ "_grok_postfix_trivial_rewrite_n 


=> [ "_grok_postfix_success" ] 


} 
} else if [program] =~ /^postfix.*\/discard$/ { 


grok { 
patterns_dir => ["/etc/logstash/patterns.d"] 
match => [ "message", "%{POSTFIX_DISCARD}" 
] 
tag_on_failure => [ "_grok_postfix_discard_nomatch" 
] 


add_tag => [ "_grok_postfix_success" ] 


# process key-value data is it exists 
if [postfix_keyvalue_data] { 


kv { 
source => "postfix keyvalue data" 
trim => "<>," 
prefix => "postfix_" 


remove field => [ "postfix keyvalue data" ] 


# some post processing of key-value data 
if [postfix client] { 


grok ( 
patterns dir -» ["/etc/logstash/patterns.d"] 
match => ["postfix client", "%{POSTFIX_ 


CLIENT INFO)"] 
tag on failure => [ " grok kv postfix client nom 


atch" ] 
remove field => [ "postfix client" ] 
} 
} 
if [postfix_relay] { 
grok { 
patterns dir => ["/etc/logstash/patterns.d"] 
match => ["postfix relay", "%{POSTFIX_R 


ELAY INFO)"] 

tag on failure -» [ " grok kv postfix relay noma 
tch" ] 

remove_field => [ "postfix_relay" ] 


} 
if [postfix_delays] { 
grok { 


patterns dir => 


["/etc/logstash/patterns.d" ] 


"%{POSTFIX_ 


[ " grok kv. postfix delays nom 


match => ["postfix delays", 

DELAYS?" ] 
tag on failure -» 

atch" ] 
remove field -» [ "postfix delays" ] 

} 
} 
} 


# Do some data type conversions 
mutate { 
convert => [ 

# list of integer fields 

"postfix anvil cache size", "integer", 
"postfix anvil conn count", "integer", 
"postfix anvil conn rate", "integer", 
"postfix client port", "integer", 
"postfix nrcpt", "integer", 
"postfix postscreen cache dropped", 
"postfix postscreen cache retained", 
"postfix postscreen dnsbl rank", 
"postfix relay port", "integer", 
"postfix server port", "integer", 
"postfix size", "integer", 
"postfix status code", "integer", 
"postfix termination signal", "integer", 
"postfix uid", "integer", 
# list of float fields 
"float", 


"postfix_delay_before_qmgr", 


"postfix_delay", 
"float", 
"postfix_delay_conn_setup", "float", 
"float", 
"float", 


"postfix_delay_in_qmgr", 
"postfix_delay_transmission", 
"postfix_postscreen_violation_time", 


"integer", 
"integer", 
"integer", 


Prenat 


配置 中 使 用 了 一 系列 自 定义 grok 正则 ， 全 部 内 容 如 下 所 示 。 保 存 成 
/etc/logstash/patterns.d/ 下 一 个 文本 文件 即 可 。 


# common postfix patterns 

POSTFIX QUEUEID ([0-9A-F]{6,}|[0-9a-zA-Z]{15,}|NOQUEUE) 

POSTFIX CLIENT INFO ?6(HOST:postfix client hostnamej?N[96(IP:postf 
ix client ip)N](:?$(INT:postfix client portj)? 

POSTFIX RELAY INFO %{HOST:postfix_relay_hostname}?\[(%{IP:postfi 
x relay ip)|9?$(DATA:postfix relay servicej)N](:96$(INT:postfix rela 
y port)? |9?4(WORD:postfix relay servicej 

POSTFIX SMTP STAGE (CONNECT |HELO|EHLO|STARTTLS | AUTH|MAIL|RCPT|DA 
TA | RSET | UNKNOWN | END- OF -MESSAGE | VRFY |. ) 

POSTFIX ACTION (reject |defer |accept |header redirect) 

POSTFIX STATUS CODE \d{3} 

POSTFIX STATUS CODE ENHANCED \d\.\d\.\d 

POSTFIX DNSBL MESSAGE Service unavailable; .* \[%{GREEDYDATA: pos 
tfix status data]*] ?$(GREEDYDATA:postfix status message); 
POSTFIX PS ACCESS ACTION (DISCONNECT|BLACKLISTED|WHITELISTED | WHI 
TELIST VETO|PASS NEW|PASS OLD) 

POSTFIX PS VIOLATION (BARE NEWLINE|COMMAND (TIME|COUNT|LENGTH) L 
IMIT|COMMAND PIPELINING|DNSBL | HANGUP|NON-SMTP COMMAND | PREGREET ) 
POSTFIX TIME UNIT 96(NUMBER) [ smhd] 

POSTFIX KEYVALUE ?6(POSTFIX QUEUEID:postfix queueid): %{GREEDYDAT 
A:postfix keyvalue data) 

POSTFIX WARNING (warning|fatal): %{GREEDYDATA: post fix_warning} 
POSTFIX TLSCONN (Anonymous|Trusted|Untrusted|Verified) TLS conne 
ction established (to %{POSTFIX RELAY INFOj)|from %{POSTFIX_CLIEN 
T INFO): 9?((DATA:postfix tls version) with cipher %{DATA: postfix 
.tls cipher) N(9?S$(DATA:postfix tls cipher size) bits\) 

POSTFIX DELAYS 9?6(NUMBER:postfix delay before qmgr)/96$(NUMBER: post 
fix delay in qmgrj)/9$(NUMBER:postfix delay conn setupj/?6$(NUMBER: p 
ostfix delay transmission) 

POSTFIX LOSTCONN (lost connection|timeout|Connection timed out) 
POSTFIX PROXY MESSAGE (9?6$(POSTFIX STATUS CODE:postfix proxy statu 
s code) )J?(94POSTFIX STATUS CODE ENHANCED:postfix proxy status c 





ode_enhanced})?.* 


# helper patterns 
GREEDYDATA NO COLON [^:]* 


# smtpd patterns 
POSTFIX SMTPD CONNECT connect from %{POSTFIX_CLIENT_INFO} 
POSTFIX SMTPD DISCONNECT disconnect from %{POSTFIX CLIENT INFO) 
POSTFIX SMTPD LOSTCONN (9?6$(POSTFIX LOSTCONN:postfix smtpd lostcon 
n data) after %{POSTFIX_SMTP_STAGE:postfix_smtp_stage}( \(%{INT} 
bytes\))? from %{POSTFIX_CLIENT_INFO}|%{GREEDYDATA: postfix acti 
on} from %{POSTFIX CLIENT INFO): %{POSTFIX LOSTCONN:postfix smtp 
d lostconn data]) 
POSTFIX SMTPD NOQUEUE NOQUEUE: %{POSTFIX ACTION:postfix action): 
%{POSTFIX_ SMTP STAGE:postfix smtp stage) from %{POSTFIX_CLIENT_ 
INFO}: 96$(POSTFIX STATUS CODE:postfix status code) %{POSTFIX_STAT 
US CODE ENHANCED:postfix status code enhanced)( <%{DATA:postfix_ 
status data)»:)? (%{POSTFIX_DNSBL_MESSAGE} |%{GREEDYDATA: postfix 
status_message}; ) %{GREEDYDATA: postfix_keyvalue_data} 
POSTFIX_SMTPD_PIPELINING improper command pipelining after %{POS 
TFIX SMTP STAGE:postfix smtp stage) from %{POSTFIX_CLIENT_INFO}: 
POSTFIX SMTPD PROXY proxy-9?6€(POSTFIX ACTION:postfix proxy result) 
(99(POSTFIX SMTP STAGE:postfix proxy smtp stage)): %{POSTFIX_PR 
OXY MESSAGE:postfix proxy message); %{GREEDYDATA: postfix_keyvalu 
e data) 


# cleanup patterns 

POSTFIX_CLEANUP_MILTER %{POSTFIX_QUEUEID: postfix_queueid}: milte 
r-%{POSTFIX_ACTION: postfix_milter_result}: %{GREEDYDATA: postfix_ 
milter_message}; %{GREEDYDATA_NO_COLON:postfix_keyvalue_data}(: 
%{GREEDYDATA: postfix_milter_data})? 


# qmgr patterns 

POSTFIX QMGR REMOVED %{POSTFIX_QUEUEID:postfix_queueid}: removed 
POSTFIX QMGR ACTIVE %{POSTFIX_QUEUEID: postfix_queueid}: %{GREEDY 
DATA:postfix keyvalue data) \(queue active\) 


# pipe patterns 
POSTFIX PIPE DELIVERED %{POSTFIX_QUEUEID: postfix_queueid}: %{GRE 
EDYDATA:postfix keyvalue data) \(delivered via %{WORD:postfix_pi 


pe_service} service\) 

POSTFIX PIPE FORWARD %{POSTFIX_QUEUEID:postfix_queueid}: %{GREED 
YDATA:postfix keyvalue data) \(mail forwarding loop for %{GREEDY 
DATA: postfix_to}\) 


# postscreen patterns 

POSTFIX_PS_CONNECT CONNECT from %{POSTFIX_CLIENT_INFO} to \[%{IP 
:postfix_server_ip}\]:%{INT:postfix_server_port} 
POSTFIX PS ACCESS %{POSTFIX_PS_ACCESS_ACTION: postfix_postscreen_ 
access) 9(POSTFIX CLIENT INFO) 

POSTFIX PS NOQUEUE %{POSTFIX_SMTPD_NOQUEUE } 

POSTFIX PS TOOBUSY NOQUEUE: reject: CONNECT from %{POSTFIX_CLIEN 
T INFO: %{GREEDYDATA: postfix_postscreen_toobusy data} 
POSTFIX PS DNSBL %{POSTFIX_PS_ VIOLATION: postfix_postscreen_viola 
tion} rank %{INT:postfix_postscreen_dnsbl_rank} for %{POSTFIX_CL 
IENT INFO? 

POSTFIX PS CACHE cache %{DATA} full cleanup: retained=%{NUMBER:p 
ostfix postscreen cache retained) dropped=%{NUMBER: postfix_posts 
creen cache dropped) entries 

POSTFIX PS VIOLATIONS 9?6$(POSTFIX PS VIOLATION:postfix postscreen 
violation)( %{INT})?( after %{NUMBER: postfix_postscreen_violatio 
n_time})? from %{POSTFIX_CLIENT_INFO}( after %{POSTFIX_SMTP_STAG 
E:postfix_smtp_stage})? 


# dnsblog patterns 
POSTFIX_DNSBLOG_LISTING addr %{IP:postfix_client_ip} listed by d 
omain %{HOST:postfix_dnsbl_domain} as %{IP:postfix_dnsbl_ result) 


# tlsproxy patterns 
POSTFIX_TLSPROXY_CONN (DIS)?CONNECT( from)? %{POSTFIX_CLIENT_INF 


0j 


# anvil patterns 

POSTFIX_ANVIL_CONN_RATE statistics: max connection rate %{NUMBER 
:postfix_anvil_conn_rate}/%{POSTFIX_TIME_UNIT:postfix_anvil_conn 

_period} for \(%{DATA:postfix_service}:%{IP:postfix_client_ip}\) 
at %{SYSLOGTIMESTAMP: postfix_anvil_timestamp} 
POSTFIX_ANVIL_CONN_CACHE statistics: max cache size %{NUMBER: pos 
tfix anvil cache size) at 9?96((SYSLOGTIMESTAMP:postfix anvil timest 


amp) 


POSTFIX ANVIL CONN COUNT statistics: max connection count %{NUMB 
ER:postfix anvil conn count) for \(%{DATA:postfix_service}:%{IP: 
postfix client ip)*) at %{SYSLOGTIMESTAMP: postfix_anvil_timestam 
pj 


4 smtp patterns 

POSTFIX SMTP DELIVERY %{POSTFIX_KEYVALUE} status-?*(WORD:postfix . 
status}( \(%{GREEDYDATA: postfix_smtp_response}\) )? 
POSTFIX_SMTP_CONNERR connect to %{POSTFIX_RELAY_INFO}: (Connecti 
on timed out|No route to host|Connection refused) 
POSTFIX_SMTP_LOSTCONN %{POSTFIX_QUEUEID: postfix_queueid}: %{POST 
FIX_LOSTCONN} with %{POSTFIX_RELAY_INFO} 


# master patterns 

POSTFIX_MASTER_START (daemon started|reload) -- version %{DATA:p 
ostfix_version}, configuration %{PATH:postfix_config_ path} 
POSTFIX_MASTER_EXIT terminating on signal %{INT:postfix_terminat 
ion_signal} 


# bounce patterns 

POSTFIX BOUNCE NOTIFICATION %{POSTFIX_QUEUEID: postfix_queueid}: 
sender (non-delivery|delivery status|delay) notification: %{POST 
FIX QUEUEID:postfix bounce queueid) 


4 scache patterns 

POSTFIX SCACHE LOOKUPS statistics: (address|domain) lookup hits- 
9 (INT:postfix scache hits) miss-?(INT:postfix scache miss) succe 
Ss-9*(INT:postfix scache success) 

POSTFIX SCACHE SIMULTANEOUS statistics: max simultaneous domains 
-9M4INT:postfix scache domains; addresses=%{INT:postfix_scache_ad 
dresses) connection-*(INT:postfix scache connection) 

POSTFIX SCACHE TIMESTAMP statistics: start interval %{SYSLOGTIME 
STAMP:postfix scache timestamp) 


4 aggregate all patterns 

POSTFIX SMTPD %{POSTFIX SMTPD CONNECT) |%{POSTFIX_SMTPD_DISCONNEC 
T}|%{POSTFIX_SMTPD_LOSTCONN} | %{POSTFIX_SMTPD_NOQUEUE} |%{POSTFIX_ 
SMTPD_PIPELINING} | %{POSTFIX_TLSCONN} |%{POSTFIX_WARNING} |%{POSTFI 
X_SMTPD_PROXY } |%{POSTFIX_KEYVALUE } 

POSTFIX_CLEANUP %{POSTFIX_CLEANUP_MILTER}|%{POSTFIX_WARNING} |%{P 


OSTFIX_KEYVALUE} 

POSTFIX QMGR %{POSTFIX_QMGR_REMOVED} |%{POSTFIX_QMGR_ACTIVE} |%{PO 
STFIX WARNING) 

POSTFIX PIPE *X(POSTFIX PIPE DELIVERED) |94(POSTFIX PIPE FORWARD) 
POSTFIX POSTSCREEN 9&(POSTFIX PS CONNECT) |9*«(POSTFIX PS ACCESS] | %{ 
POSTFIX_PS_NOQUEUE} |%{POSTFIX_PS_TOOBUSY} |%{POSTFIX_PS_CACHE} |%{ 
POSTFIX_PS_DNSBL}|%{POSTFIX_PS_VIOLATIONS} |%{POSTFIX_WARNING} 
POSTFIX_DNSBLOG %{POSTFIX_DNSBLOG_LISTING} 

POSTFIX ANVIL %{POSTFIX_ANVIL_CONN_RATE} |%{POSTFIX_ANVIL_CONN_CA 
CHE) |%{POSTFIX_ANVIL_CONN_COUNT} 

POSTFIX SMTP %{POSTFIX_SMTP_DELIVERY}|%{POSTFIX_SMTP_CONNERR} | %{ 
POSTFIX_SMTP_LOSTCONN}|%{POSTFIX_TLSCONN} |%{POSTFIX_WARNING} 
POSTFIX DISCARD %{POSTFIX_KEYVALUE} status=%{WORD:postfix_status 
} 

POSTFIX_LMTP %{POSTFIX_SMTP} 

POSTFIX_PICKUP %{POSTFIX_KEYVALUE} 

POSTFIX_TLSPROXY %{POSTFIX_TLSPROXY_CONN} 

POSTFIX MASTER *(POSTFIX MASTER START) |%{POSTFIX_MASTER_EXIT} 
POSTFIX BOUNCE *(POSTFIX BOUNCE NOTIFICATION] 

POSTFIX SENDMAIL %{POSTFIX WARNING) 

POSTFIX POSTDROP 9£((POSTFIX WARNING) 

POSTFIX SCACHE %{POSTFIX_SCACHE_LOOKUPS} |%{POSTFIX_SCACHE_SIMULT 
ANEOUS} | %{POSTFIX_SCACHE_TIMESTAMP} 

POSTFIX_TRIVIAL_REWRITE %{POSTFIX_WARNING} 

POSTFIX_TLSMGR %{POSTFIX_WARNING} 

POSTFIX_LOCAL %{POSTFIX_KEYVALUE} 





ossec 


本 节 作 者 : 林 鹏 


配置 QOSSEC SYSLOG 输出 (所 有 agent) 


1. 编辑 ossec.conf 文件 (默认 为 /varossec/etc/ossec.conf ) 
2. 在 ossec.conf 中 添加 下 列 内 容 〈10.0.0.1 为 接收 syslog 的 服务 器 ) 


<syslog_output> 
<server>10.0.0.1</server> 
<port>9000</port> 


<format>default</format> 
</syslog_output> 


1. 开启 OSSEC 人 允许 syslog 输 出 功能 


/var/ossec/bin/ossec-control enable client-syslog 


1. 重启 OSSEC 服 务 


/var/ossec/bin/ossec-control start 


Ac 2 LOGSTASH 


1. 在 logstash 中 配置 文件 中 增加 (或 新 建 ) 如 下 内 容 : (假设 10.0.0.1 为 ES 服务 
器 ,假设 文件 名 为 logstash-ossec.conf ) 


port => 9000 
type => "syslog" 


j 
} 
filter { 
if [type] == "syslog" { 


grok { 
match => { "message" => "%{SYSLOGTIMESTAMP:syslog_ti 
mestamp} %{SYSLOGHOST:syslog_ host} %{DATA:syslog_program}: Alert 
Level: %{BASE1ONUM:Alert_Level}; Rule: %{BASE1@NUM:Rule} - %{GR 
EEDYDATA:Description}; Location: %{GREEDYDATA:Details}" } 
add field => [ "ossec server", "%{host}" ] 
j 
mutate { 
remove field => [ "syslog hostname", "syslog message 
", "Syslog pid", "message", "Qversion", "type", "host" ] 


j 
j 
j 
output { 
elasticsearch http { 
host => "10.0.0.1" 
j 
j 


推荐 Kibana dashboard 


社区 已 经 有 人 根据 ossec 的 常见 需求 ， 制 作 有 dashboard 可 以 直接 从 Kibana3 页 
面 加 载 使 用 。 
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dashboard 的 JSON 文件 
JL : https://github.com/magenx/Logstash/raw/master/kibana/kibana dashboard.js 
on 


加 载 方 式 ， 请 阅读 本 书 稍 后 Kibana = ?38 X^ € » 


Windows Event Log 


前 面 说 过 如 何在 windows 上 利用 nxlog 传输 日 志 数据 。 事 实 上 ， 对 于 windows 本 
身 ， 也 有 类 似 syslog 的 设计 ， 叫 eventlog » Z& 9 4-28 4e 44 4b 3€. windows 
eventlog ° 


AK Ae 3m BC E 
logstash 配置 


input { 
eventlog { 
#logfile => ["Application", "Security", "System" ] 
logfile => ["Security"] 
type => "winevent" 
tags => [ "caen" ] 


nxlog 配置 


## This is a sample configuration file. See the nxlog reference 
manual about the 

## configuration options. It should be installed locally and is 
also available 

## online at http://nxlog.org/nxlog-docs/en/nxlog- reference -manu 
al. html 


## Please set the ROOT to the folder your nxlog was installed in 
to, 
## otherwise it will not start. 


#define ROOT C:\Program Files\nxlog 
define ROOT C:\Program Files (x86)\nxlog 


Moduledir %ROOT%\modules 
CacheDir %ROOT%\data 

Pidfile %ROOT%\data\nxlog.pid 
SpoolDir %ROOT%\data 

LogFile %ROOT%\data\nxlog.log 


<Extension json> 
Module xm_json 


</Extension> 


<Input in> 


Module im_msvistalog 
# For windows 2003 and earlier use the following: 
# Module im_mseventlog 

Exec to_json(); 
</Input> 


<Output out> 


Module om_tcp 

Host 10.66.66.66 

Port 5140 
</Output> 
<Route 1> 

Path in => out 
</Route> 


Logstash 解析 配置 


input { 
tcp { 
codec => "json" 
port => 5140 
tags => ["windows","nxlog" ] 
type => "nxlog-json" 
} 
) # end input 


filter { 
if [type] == "nxlog-json" { 
date { 
match => ["[EventTime]", "YYYY-MM-dd HH:mm:ss"] 
timezone => "Europe/London" 
j 
mutate { 
rename => [ "AccountName", "user" ] 
rename => [ "AccountType", "[eventlog][account type]" ] 
rename -» [ "ActivityId", "[eventlog][activity id]" ] 
rename -» [ "Address", "ipe" ] 
rename -» [ "ApplicationPath", "[eventlog][application p 
ath]" ] 
rename -» [ "AuthenticationPackageName", "[eventlog][aut 
hentication package name]" ] 
rename -» [ "Category", "[eventlog][category]" ] 
rename -» [ "Channel", "[eventlog][channel]" ] 
rename -» [ "Domain", "domain" ] 
rename -» [ "EventID", "[eventlog][event id]" ] 
rename -» [ "EventType", "[eventlog][event type]" ] 
rename -» [ "File", "[eventlog][file path]" ] 
rename -» [ "Guid", "[eventlog][guid]" ] 
rename -» [ "Hostname", "hostname" ] 
rename -» [ "Interface", "[eventlog][interface]" ] 
rename -» [ "InterfaceGuid", "[eventlog][interface guid] 


él 

rename -» [ "InterfaceName", "[eventlog][interface name] 
ts] 

rename -» [ "IpAddress", "ip" ] 

rename -» [ "IpPort", "port" ] 

rename -» [ "Key", "[eventlog][key]" ] 

rename -» [ "LogonGuid", "[eventlog][logon guid]" ] 

rename -» [ "Message", "message" ] 

rename -» [ "ModifyingUser", "[eventlog][modifying user] 
es] 


rename -» [ "NewProfile", "[eventlog][new profile]" ] 
rename -» [ "OldProfile", "[eventlog][old profile]" ] 
rename => [ "Port", "port" ] 

rename => [ "PrivilegeList", "[eventlog][privilege list] 


rename 
rename 
rename 


rename 
rename 


rename 
rename 
rename 


rename 
rename 
rename 

ain name]" ] 


rename 
d]" ] 
rename 
name]" ] 
rename 
id]" ] 
rename 
rename 


n_name]" ] 


rename 
" ] 
rename 
me]" ] 
rename 
] 
rename 
} 
mutate { 


=> [ 


"ProcessID", "pid" ] 

"ProcessName", "[eventlog][process name]" ] 
"ProviderGuid", "[eventlog][provider guid]" 
"ReasonCode", "[eventlog][reason code]" ] 
"RecordNumber", "[eventlog][record number]" 
"ScenarioId", "[eventlog][scenario id]" ] 
"level" ] 


"SeverityValue", 


"Severity", 
"[eventlog][severity code]" 


"SourceModuleName", 
"[eventlog][program]" ] 
"SubjectDomainName", "[eventlog][subject dom 


"nxlog input" ] 
"SourceName", 


"SubjectLogonId", "[eventlog][subject logoni 


"SubjectUserName", "[eventlog][subject user 


"SubjectUserSid", "[eventlog][subject user s 


"System", "[eventlog][system]" ] 
"TargetDomainName", "[eventlog][target domai 


"TargetLogonId", "[eventlog][target logonid] 


"TargetUserName", "[eventlog][target user na 
"TargetUserSid", "[eventlog][target user sid 


"ThreadID", "thread" ] 


remove field => [ 


"CurrentOrNextState", 
"Description", 
"EventReceivedTime", 
"EventTime", 
"EventTimewritten", 


"IPVersion", 
"KeyLength", 
"Keywords", 
"LmPackageName", 
"LogonProcessName", 
"LogonType", 

"Name", 

"Opcode", 
"OpcodeValue", 
"PolicyProcessingMode", 
"Protocol", 
"ProtocolType", 
"SourceModuleType", 
"State", 

"Task", 
"TransmittedServices", 
"Type", 

"UserID", 

"Version" 


] 


Java 日 志 


提 到 过 ， 对 Java 日 志 ， 除 了 使 用 multiline 做 多 行 日 志 合 


之 前 在 codec 章节 ， 曾 经 
义 直 接 通过 log4j 写 入 到 logstash 里 。 本 节 就 讲述 如 何在 Java 应 用 


并 以 外 ， 还 可 » 
环境 做 到 这 点 。 


Log4J 


首先 ， 需 要 配置 Java 应 用 的 Log4J 设置 ， 启 动 一 个 内 置 的 SocketAppender ° 
修改 应 用 的 log4j.xml 配置 文件 ， 添 加 如 下 配置 段 : 


«appender name="LOGSTASH" class="org.apache.1log4j.net.SocketAppe 
nder"> 

«param name="RemoteHost" value="logstash_hostname" /> 

<param name="ReconnectionDelay" value="60000" /> 

<param name="LocationInfo" value="true" /> 

<param name="Threshold" value="DEBUG" /> 
</appender> 


然后 把 这 个 新 定义 的 appender 对 象 加 入 到 root logger 里 ， 可 以 跟 其 他 已 有 logger 
共存 : 


<root> 
<level value="INFO"/> 
<appender-ref ref="OTHERPLACE"/> 
<appender-ref ref="LOGSTASH"/> 
</root> 


如 果 是 log4j.properties 配置 文件 ， 则 对 应 配置 如 下 : 


log4j.rootLogger-DEBUG, logstash 


###SocketAppender### 
1og4j.appender.logstash-org.apache.log4j.net.SocketAppender 
log4j.appender.logstash.Port-4560 
log4j.appender.logstash.RemoteHost-logstash hostname 
1og4j.appender.logstash.ReconnectionDelay-60000 

log4j .appender.logstash.LocationInfo=true 


Log4J 会 持续 尝试 连接 你 配置 的 logstash hostname 这 个 地 址 ， 建 立 连接 后 ， 即 开 


始 发 送 日 志 数 据 。 


Logstash 


Java 应 用 端的 配置 完成 以 后 ， 开 始 设置 Logstash 的 接收 端 。 配 置 如 下 所 示 
4560 端口 是 Log4J SocketAppender 的 默认 对 端 端口 。 


input { 
log4j { 


type => "log4j-json" 
port => 4560 


异常 堆栈 测试 验证 


运行 起 来 logstash 后 ， 编 写 如 下 一 个 简单 log4j 程序 : 


。 其 中 


import org.apache.10g4j.Logger; 
public class HelloExample{ 
final static Logger logger = Logger.getLogger (HelloExamp 
le.class); 
public static void main(String[] args) { 
HelloExample obj = new HelloExample(); 
tryt 
obj.divide(); 
jcatch(ArithmeticException ex) { 
logger.error("Sorry, something wrong!", 


ex); 
} 
} 
private void divide(){ 
int i = 10 /0; 
} 
} 
编译 运行 : 


# javac -cp ./logstash-1.5.0.rc2/vendor/bundle/jruby/1.9/gems/lo 
gstash-input -log4j-0.1.3-java/lib/1log4j/1l0g4j/1.2.17/1log4j-1.2.1 
7.jar HelloExample.java 

# java -cp .:./logstash-1.5.0.rc2/vendor/bundle/jruby/1.9/gems/1 
ogstash-input-10g4j-0.1.3-java/lib/log4j/109g4j/1.2.17/1094j-1.2. 
17.jar HelloExample 


即 可 在 logstash 的 终端 输出 看 到 如 下 事件 记录 : 


"message" 
"@version" 
"@timestamp" 
"type" 

"host" 

"path" 
"priority" 
"logger name" 
"thread" 
"class" 
"file" 
"method" 
"stack trace" 


Ntat HelloExample. 


=> "Sorry, something wrong!", 
a ile 

=> "2015-07-02T13:24:45.727Z", 
=> "log4j-json", 

=> "127.0.0.1:52420", 

=> "HelloExample", 


=> "ERROR", 
=> "HelloExample", 
E "main", 


-» "HelloExample", 

=> "HelloExample.java:9", 

=> "main", 

=> "java.lang.ArithmeticException: / by zero\n 
divide(HelloExample. java:13)\n\tat HelloExampl 


e.main(HelloExample.java:7)" 


} 


可 以 看 到 ， 弄 常 堆栈 直接 就 记录 在 单行 内 了 。 


JSON Event layout 


如 果 无 法 采用 socketappender ， 必 须 使 用 文件 方式 的 ， 其 实 Log4J 有 一 个 layout 
特性 ， 用 来 控制 日 志 输 出 的 格式 。 和 Nginx 日 志 自 己 拼接 ISON 输出 类 似 ， 也 可 以 
通过 layout 功能 ， 记 录 成 JSON 格式 。 推 荐 使 

用 : https://github.com/logstash/log4j-jsonevent-layout 


MySQL 慢 查询 日 志 


MySQL 有 多 种 日 志 可 以 记录 ， 常 见 的 有 error log ` slow log ` general log ` bin log 
等 。 其 中 slow log 作为 性 能 监控 和 优化 的 入 手 点 ， 最 为 首要 。 本 节 即 讨论 如 何 用 
logstash 处 理 slow log。 至 于 general log， 格 式 处 理 基本 类 似 ， 不 过 由 于 general 
量 级 比 slow 大 得 多 ， 推 荐 采用 packetbeat 协议 解析 的 方式 更 高 效 的 完成 这 项 工 
作 。 相 关内 容 阅读 本 书 稍 后 章节 。 


MySQL slow log 的 logstash 处 理 配 置 示 例如 下 : 


input { 
file { 
type => "mysql-slow" 
path => "/var/log/mysql/mysql-slow. log" 
codec => multiline { 
pattern => "A# User@Host:" 
negate => true 
what => "previous" 


filter { 
# drop sleep events 
grok { 
match => { "message" => "SELECT SLEEP" } 
add tag => [ "sleep drop" ] 
tag on failure => [] £ prevent default _grokparsefailure tag 
on real records 
} 
if "sleep drop" in [tags] { 
drop {} 
} 
grok { 
match => [ "message", "(?m)^£ UserQHost: %{USER:user}\[[^\]] 
+\] Q (?:(?<clienthost>\S*) )?\[(?:%{IP:clientip})?\]\s*# Query 
time: %{NUMBER: query_time:float}\s+Lock_time: %{NUMBER: lock time 
:float}\s+Rows_sent: %{NUMBER: rows_sent:int}\s+Rows_examined: %{ 
NUMBER: rows_examined:int}\s*(?:use %{DATA:database};\s*)?SET tim 
estamp=%{NUMBER: timestamp}; \s*(?<query>(?<action>\w+)\st+.*)\n# T 
ime:.*$" ] 
} 
date { 
match => [ "timestamp", "UNIX" ] 
remove_field => [ "timestamp" ] 


47 B6 E. » logstash 即 可 将 多 行 的 MySQL slow log 处 理 成 如 下 事件 : 


"@timestamp" => "2014-03-04T19:59:06.000Z", 

"message" => "# User@Host: logstash[logstash] @ localh 
ost [127.0.0.1]\n# Query time: 5.310431 Lock time: 0.029219 Row 
s sent: 1 Rows examined: 24575727NnSET timestamp=1393963146; \ns 
elect count(*) from node join variable order by rand();\n# Time: 

140304 19:59:14", 
"Qversion" => "i", 
"tags" => [ 
[0] "multiline" 
], 
"type" => "mysql-slow", 
"host" => "raochenlindeMacBook-Air.local", 
"path" => "/var/1log/mysql/mysql-slow.log", 
"user" => "logstash", 
"clienthost" => "localhost", 
"clientip" => "127.0.0.1", 
"query time" => 5.310431, 
"lock time" -» 0.029219, 
"rows sent" -» 1, 
"rows examined" => 24575727, 
"query" => "select count(*) from node join variable 
order by rand();", 
"action" => "select" 


性 能 与 测试 


任何 软件 都 需要 掌握 其 性 能 瓶颈 ， 以 及 线 上 运行 时 的 性 能 状态 。Logstash 也 不 例 
外 。 


长 久 以 来 ，Logstash 在 这 方面 一 直 处 于 比较 黑 盒 的 状态 。 因 为 其 内 部 队列 使 用 的 是 
标准 的 stud 库 ， 并 非 自 己 实现 ， 在 Logstash 本 身 源 代码 里 是 找 不 出 来 什么 问题 
的 。 我 们 只 能 按照 其 pipeline 原理 ， 总 结 出 来 一 些 模拟 检测 的 手段 。 


在 Logstash-5.0.0 中 ， 一 大 改进 就 是 学 习 Elasticsearch 的 方式 ， 通 过 API 提供 了 
一 部 分 运行 性 能 指标 | 本 节 就 会 介绍 这 方面 的 内 容 。 同 时 ， 作 为 极限 压 测 的 方式 ， 
依然 会 介绍 一 些 模拟 数据 的 生成 和 SVM 指标 观测 方法 。 


生成 测试 数据 (Generator) 


实际 运行 的 时 候 这 个 插件 是 派 不 上 用 途 的 ， 但 这 个 插件 依然 是 非常 重要 的 插件 之 
一 。 因 为 每 一 个 使 用 ELK stack 的 运 维 人 员 都 应 该 清楚 一 个 道理 : 数据 是 支持 操作 
&j"E— RE (否则 你 也 用 不 着 ELK) 。 所 以 在 上 线 之 前 ， 你 一 定 会 需要 在 自己 的 实 
际 环境 中 ， 测 试 Logstash 和 Elasticsearch 的 性 能 状况 。 这 时 候 ， 这 个 用 来 生成 测 
试 数据 的 插件 就 有 用 了 ! 


配置 示例 


input { 
generator { 
count => 10000000 
message => '("keyi":"value1","key2":[1,2], "key3":("subke 
yi":"subvaluei"}}' 
codec => json 


插件 的 默认 生成 数据 ，message A RÆ "hello world"。 你 可 以 根据 自己 的 实际 需要 
这 里 来 写 其 他 内 容 。 


使 用 方式 
做 测试 有 两 种 主要 方式 : 
e 配合 LogStash::Outputs::Null 


inputs/generator 是 无 中 生 有 ，output/null 则 是 锯 嘴 请 芦 。 事 件 流转 到 这 里 直接 就 略 
过 ， 什 么 操作 都 不 做 。 相 当 于 只 测试 Logstash 的 pipe 和 filter 效率 。 测 试 过 程 非 
常 简单 : 


$ time ./bin/logstash -f generator_null.conf 
real 3m0.864s 

user 3m39.031s 

sys 0m51.621s 


e 使 用 pv 命令 配合 LogStash::Outputs::Stdout 和 LogStash::Codecs::Dots 


上 面 的 这 种 方式 虽然 想法 挺 好 ， 不 过 有 个 小 漏洞 : logstash 是 在 JVM 上 运行 的 ， 
有 一 个 明显 的 启动 时 间 ， 运 行 也 有 一 段 事 件 的 预 热 后 才 算 稳定 运行 。 所 以 ， 要 想 更 
i& 3: 84 RE logstash 在 长 期 运行 时 候 的 效率 ， 还 有 另 一 种 方法 : 


output { 
stdout { 
codec => dots 


LogStash::Codecs::Dots 也 是 一 个 另类 的 codec 插件 ， 他 的 作用 是 : 把 每 个 event 
都 变 成 一 个 点 ( ， )。 这 样 ， 在 输出 的 时 候 ， 就 变 成 了 一 个 一 个 的 o. ERE 
显然 这 也 是 一 个 为 了 测试 而 存在 的 插件 。 


下 面 就 要 介绍 pv 命令 了 。 这 个 命令 的 作用 ， 就 是 作 实时 的 标准 输入 、 标 准 输出 监 
控 。 我 们 这 里 就 用 它 来 监控 标准 输出 : 


$ ./bin/logstash -f generator_dots.conf | pv -abt > /dev/null 
2.2MiB 0:03:00 [12.5kiB/s] 


可 以 很 明显 的 看 到 在 前 几 秒 中 ， 速 度 是 B/s » AA JVM 还 没 启动 起 来 呢 。 开 始 运 
行 的 时 候 ， 速 度 依 然 不 快 。 慢 慢 增 长 到 比较 稳定 的 状态 ， 这 时 候 的 才 是 你 需要 的 数 
dE o 


这 里 单位 是 B/s， 但 是 因为 一 个 event 就 输出 一 个 ，， 也 就 是 1B。 所 以 
12.5kiB/s 就 相当 于 是 12.5k event/s ° 


注 : 如 果 你 在 CentOS 上 通过 yum 安装 的 pv 命令， 版 本 较 低 ， 可 能 还 不 支持 -a 
RR o PAE -bt 参数 看 起 来 还 是 有 点 累 的 。 


如 果 你 要 测试 的 是 input 插件 的 效率 ， 方 法 也 是 类 似 的 。 此 外 ， 如 果 不 想 使 用 额外 
而 且 可 能 低 版 本 的 pv 命令 ， 通 过 logstash-filter-metric 插件 也 可 以 做 到 类 似 的 效 
果 ， 官 方 博客 中 对 此 有 详细 阐述 ， 建 议 大 家 阅读 。 


额外 的 话 


既然 单独 花 这 么 一 节 来 说 测试 ， 这 里 想 额 外 谈 谈 一 个 很 常见 的 话题 ELK 的 性 能 
怎么 样 ? 


其 实 这 压根 就 是 一 个 不 正确 的 提问 。ELK 并 不 是 一 个 软件 而 是 一 个 并 不 辜 合 的 套 
件 。 所 以 ， 我 们 需要 分 折 开 讨论 这 三 个 软件 的 性 能 如 何 ? 怎么 优化 ? 


e LogStash 的 性 能 ， 是 最 让 新 人 迷惑 的 地 方 。 因 为 LogStash 本 身 并 不 维护 队 
列 ， 所 以 整个 日 志 流 转 中 任意 环节 的 问题 ， 都 可 能 看 起 来 像 是 LogStash 的 问 
题 。 这 里 ， 需 要 熟练 使 用 本 节 说 的 测试 方法 ， 针 对 自己 的 每 一 段 配置 ， 都 确定 
其 性 能 。 另 一 方面 ， 就 是 本 书 之 前 提 到 过 的 ，LogStash 给 自己 的 线程 都 设置 
了 单独 的 线程 名 称 ， 你 可 以 在 top -H 结果 中 查看 具体 线程 的 负载 情况 。 


e Elasticsearch 的 性 能 。 这 里 最 需要 强调 的 是 : Elasticsearch 是 一 个 分 布 式 系 
统 。 从 来 没有 分 布 式 系统 要 跟 人 比较 单机 处 理 能 力 的 说 法 。 所 以 ， 更 需要 关注 
的 是 : 在 确定 的 单机 处 理 能 力 的 前 提 下 ， 性 能 是 否 能 做 到 线性 扩展 。 当 然 ， 这 
不 意味 着 说 提高 处 理 能 力 只 能 千 加 机 器 了 一 一 有 效 利 用 mapping API 是 非常 重 
要 的 。 不 过 暂时 就 在 这 里 讲述 了 。 


e Kibana 的 性 能 。 通 常 来 说 ，Kibana 只 是 一 个 单 页 Web 应 用 ， 只 需要 nginx 发 
布 静态 文件 即 可 ， 没 什么 性 能 问题 。 页 面 加 载 缓慢 ， 基 本 上 是 因为 
Elasticsearch 的 请 求 响应 时 间 本 身 不 够 快 导致 的 。 不 过 一 定 要 细 究 的 话 ， 也 能 
找 出 点 Kibana 本 身 性 能 相关 的 话题 : 因为 Kibana3 默认 是 连接 固定 的 一 个 
ES 节点 的 IP 端口 的 ， 所 以 这 里 会 涉及 一 个 浏览 器 的 同一 IP 并 发 连接 数 的 限 
制 。 其 次 ， 就 是 Kibana 用 的 AngularJS 使 用 了 Promise.then 的 方式 来 处 理 
HTTP 请 求 响应 。 这 是 异步 的 。 


心跳 检测 


缺少 内 部 队列 状态 的 监控 办 法 一 直 是 logstash 最 为 人 诉 病 的 一 点 。 从 logstash- 


1.5.1 版 开始 ， 新 发 布 了 一 个 logstash-input-heartbeat 插件 ， 实 现 了 一 个 最 基本 的 
队列 堵塞 状态 监控 。 


配置 示例 如 下 : 


input { 
heartbeat { 

message => "epoch" 

interval => 60 

type => "heartbeat" 

add_field => { 
"Zbxkey" => "logstash.heartbeat", 
"Zbxhost" => "logstash hostname" 


} 
} 
tcp { 
port => 5160 
} 
} 
output { 
if [type] == "heartbeat" { 
file { 
path => "/data1/logstash-log/local6-5160-%{+YYYY.MM. 
dd) . log" 
} 
zabbix { 
zabbix_host => "zbxhost" 
zabbix_key => "zbxkey" 
zabbix_server_host => "zabbix.example.com" 
zabbix_value => "clock" 
} 
} else { 
elasticsearch { } 
} 
} 


示例 中 ， 同 时 将 数据 输出 到 本 地 文件 和 zabbix server » ix: € > logstash-output- 
zabbix 并 不 是 标准 插件 ， 需 要 额外 安装 : 


bin/logstash-plugin install logstash-output -zabbix 


文件 中 记录 的 就 是 heartbeat 事件 的 内 容 ， 示 例如 下 : 


{"clock":1435191129, "host":"logtes004.mweibo.bx.sinanode.com", "@ 
version":"1","Qtimestamp":"2015-06-25T00:12:09.042Z", " type" :"hea 
rtbeat", "zbxkey":"logstash.heartbeat", 'zbxhost":"logstash hostna 


me") 


可 以 通过 文件 最 后 的 clock 和 (og timestamp 内 容 ， 对 比 当前 时 间 ， 来 判断 logstash 
内 部 队列 是 否 有 堵塞 。 


JMX 监控 方式 


Logstash 是 一 个 运行 在 JVM 上 的 软件 ， 也 就 意味 着 JMX 这 种 对 JVM 的 通用 监控 
方式 对 Logstash 也 是 一 样 有 效果 的 。 要 给 Logstash 启用 JMX， 需 要 修改 
./bin/logstash.lib.sh 中 $JAVA OPTS 变量 的 定义 ， 或 者 在 运行 时 设置 

LS JAVA OPTS 环境 变量 。 


在 ./bin/logstash.lib.sh 第 34 行 JAVA_OPTS="$JAVA_OPTS - 
Djava.awt.headless-true" 下 ， 添 加 如 下 几 行 : 


JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote" 

JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.port-90 
10" 

JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.local.o 
nly=false" 

JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.authent 
icate=false" 

JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.ssl-fal 
se" 


重启 logstash IR 4 > JMX 配置 即 可 生效 。 


有 JMX 以 后 ， 我 们 可 以 通过 jconsole 界面 查看 ， 也 可 以 通过 zabbix 等 监控 系统 做 
长 期 监控 。 甚 至 logstash 自己 也 有 插件 logstash-input-jmx 来 读 取 远程 JMX 数 
据 。 


zabbix 监控 


zabbix 里 提供 了 专门 针对 JMX 的 监控 项 。 详 
Ju:https://www.zabbix.com/documentation/2.2/manual/config/items/itemtypes/jmx_ 
monitoring 


i£ & > zabbix-server 本 身 并 不 直接 对 JMX 发 起 请 求 ， 而 是 单独 有 一 个 Java 
Gateway 作为 中 间 代 理 层 角色 。zabbix-server 的 java poller 连接 zabbix-java- 
gateway， 由 zabbix-java-gateway 去 获取 远程 JMX 信息 。 所 以 ， 在 zabbix-web 
配置 之 前 ， 需 要 先 配置 zabbix server 相关 进程 和 设置 : 


# yum install zabbix-java-gateway 

# cat >> /etc/zabbix/zabbix-server.conf ««EOF 
JavaGateway=127.0.0.1 

JavaGatewayPort=10052 

StartJavaPollers=5 

EOF 

# /etc/init.d/zabbix-java-gateway restart 

# /etc/init.d/zabbix-server restart 


然后 在 zabbix-web 上 Configuration 页 ， 给 运行 logstash 的 主机 的 Host 配置 添 
加 JMX interfaces，Port 即 为 上 面 定 义 的 9010 端口 。 


最 后 添加 Item > Type 下 拉 框 选择 JMX agent > Key 文本 框 输入 
jmx["java.lang:type-Memory", "HeapMemoryUsage.used"] ， 保 存 即 可 。 


JMX 有 很 多 Key 可 以 监控 ， 具 体 的 值 ， 可 以 通过 jconsole 参看 。 如 下 图 所 示 ， 如 


果 要 监控 线程 数 ， 就 可 以 写成 jmx["java.lang:type-Threading", 
"ThreadCount"] ° 
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有 了 监控 项 和 数据 ， 后 续 的 Graph, Screen, Trigger 定义 ， 这 里 就 不 再 讲述 了 ， 有 
需要 的 读者 可 以 自行 查找 Zabbix 相关 资料 。 


Logstash 的 监控 API 


Logstash 5.0 开始 ， 提 供 了 输出 自身 进程 的 指标 和 状态 监控 的 APl。 这 大 大 降低 了 
我 们 监控 Logstash 的 难度 。 


目前 API 主要 有 四 类 : 


e 节点 信 息 
e 插件 信息 
e 节点 指标 
e 热线 程 统计 


node info 接口 目前 支持 三 种 类 型 : pipeline ^ os ^ jum » ALRK e 


插件 信息 


用 来 列 出 已 安装 插件 的 名 称 和 版 本 。 


节点 指标 


node stats 接口 目前 支持 四 种 类 型 的 指标 : 


events 


获取 该 指标 的 方式 为 : 
curl -s localhost:9600/_node/stats/events?pretty=true 


4X 8] > Logstash 跟 Elasticsearch 一 样 也 支持 用 ?pretty 参数 美化 JSON 输 

出 。 此 外 ， 还 支持 ?format=yam1 来 输出 YAML 格式 的 指标 统计 。Logstash 3X 
认 监 听 在 9600 端口 提供 这 些 API 访问 。 如 果 需 要 修改 ， 通 过 --http.port 命 
令 行 参数 ， 或 者 对 应 的 logstash.yml 设置 修改 。 


该 指标 的 响应 结果 示例 如 下 : 


"events" : { 
"in" : 59685, 
"filtered" : 59685, 
"out = 59685 


jvm 
获取 该 指标 的 方式 为 : 


curl -s localhost:9600/_node/stats/jvm?pretty=true 


该 指标 的 响应 结果 示例 如 下 : 


{ 
"jvm" s f 
"threads" : { 
"count" : 32, 
"peak_count" : 34 
} 
} 
} 
process 
获取 该 指标 的 方式 为 : 


curl -s localhost:9600/_node/stats/process?pretty=true 


该 指标 的 响应 结果 示例 如 下 : 





"process" : { 
"peak open file descriptors" : 64, 
"max file descriptors" : 10240, 
"open file descriptors" : 64, 
"mem" : { 
"total virtual in bytes" : 5278068736 
i 
"cpu cs 
"total in millis" : 103290097000, 
"percent" : 0 
} 


目前 beats 家 族 有 个 logstashbeat 项 目 ， 就 是 专门 采集 这 个 数据 的 。 


pipeline 
获取 该 指标 的 方式 为 : 


curl -s localhost:9600/_node/stats/pipeline?pretty=true 


该 指标 的 响应 结果 示例 如 下 : 


"pipeline": { 
"events": { 
"durat lon ain Millis’: 7863504, 
"geo. 
"filtered": 100, 
"out": 100 
ty 
Molugins == fi 
"Inputs: qp 
PEL Cers sai 
{ 
"id": "grok 20e5cb7f7c9e712ef9750edf94aefb46 


generator” X 


5e3e361b-2", 

"events": { 
"duration in millzs"* 48, 
ln 10097 
"out" > 100 

tr 

"matches": 100, 

"patterns per field": { 
"message": 1 


ty 
"name": "grok" 
ty 
{ 
"id": "geoip_20e5cb7f7c9e712ef9750edf94aefb4 
65e3e361b-3", 
"events": { 
“duration in millis’: 141. 
rine. 100, 
rout: 200 
ty 
"name": "geoip" 
} 
]， 
TOUEpIUGS :el 
{ 
"id": "20e5cb7f7c9e712ef9750edf94aefb465e3e3 
61b-4", 
"events": { 
D LOG): 
"ots 109 
tr 
"name": "elasticsearch" 
} 
] 


ty 

"reloads": { 
astaernmonr muli? 
"successes": 0, 
"last_success_timestamp": null, 
"last failure timestamp": null, 
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"failures": 0 


可 以 看 到 它 这 里 显示 了 每 个 插件 的 日 志 处 理 情况 (数量 、 耗 时 等 )， 尤 其 是 grok IE 
器 插件 2 还 显示 出 来 了 正则 匹配 失败 的 数量 M 每 个 字段 匹配 的 正则 表达 式 个 数 等 很 
有 用 的 排 障 和 性 能 调 优 信息 。 


热线 程 统计 
上 面 的 指标 值 可 能 比较 适合 的 是 长 期 趋势 的 监控 ， 在 排 障 的 时 候 ， 更 需要 的 是 即时 


的 线程 情况 统计 。 获 取 方 式 如 下 : 


curl -s localhost:9600/_node/stats/hot_threads?human=true 


该 接口 默认 返回 也 是 JSON 格式 ， 在 看 堆栈 的 时 候 并 不 方便 ， 可 以 用 2 
human=true 参数 来 改 成 文本 换行 的 样式 。 效 果 上 跟 我 们 看 Elasticsearch 的 
/_nodes/_local/hot_threads 效果 就 一 样 了 。 


其 实 节点 指标 AP| 也 有 ?human=true 参数 ， 其 作用 和 hot_threads 不 一 样 ， 
是 把 一 些 网 络 字 节 数 啊 ， 时 间 啊 ， 改 成 人 类 更 易 懂 的 大 单位 。 


扩展 方案 


之 前 章节 中 ， 讲 述 的 都 是 单个 logstash 进程 ， 如 何 配置 实现 对 数据 的 读 取 、 解 析 和 
输出 处 理 。 但 是 在 生产 环境 中 ， 从 每 台 应 用 服务 器 运行 logstash 进程 并 将 数据 直接 
发 送 到 Elasticsearch 里 ， 显 然 不 是 第 一 选择 : 第 一 ， 过 多 的 客户 端 连 接 对 
Elasticsearch 是 一 种 额外 的 压力 ; 第 二 ， 网 络 抖动 会 影响 到 logstash 进程 ， 进 而 
影响 生产 应 用 ; 第 三 ， 运 维 人 员 未 必 愿 意 在 生产 服务 器 上 部 署 Java， 或 者 让 
logstash 跟 业 务 代码 争夺 Java 资源 。 


所 以 ， 在 实际 运用 中 ，logstash 进程 会 被 分 为 两 个 不 同 的 角色 。 运 行 在 应 用 服务 器 
上 的 ， 尺 量 减轻 运行 压力 ， 只 做 读 取 和 和 转发， 这 个 角色 叫做 shipper ; 运行 在 独立 
服务 器 上 ， 完 成 数据 解析 处 理 ， 负 责 写 入 Elasticsearch 49 4 & » "| indexer ° 





logstash 作为 无 状态 的 软件 ， 配 合 消 息 队 列 系 统 ， 可 以 很 轻松 的 做 到 线性 扩展 。 本 
节 首 先 会 介绍 最 常见 的 两 个 消息 队列 与 logstash 的 配合 。 


此 外 ，logstash 作为 一 个 框架 式 的 项 目 ， 并 不 排斥， 甚至 欢迎 与 其 他 类 似 软件 进行 
混搭 式 的 运行 。 本 节 也 会 介绍 一 些 其 他 日 志 处 理 框架 以 及 如 何 和 logstash 共存 的 方 
A ( 《logstashbook》 也 同样 有 类 似 内 容 ) 。 和 希望 大 家 各 取 所 长 ， 做 好 最 适合 自己 
的 日 志 处 理 系统 。 


利用 Redis 队列 扩展 logstash 


Redis 服务 器 是 logstash 官方 推荐 的 broker 选择 。Broker 角色 也 就 意味 着 会 同时 
存在 输入 和 输出 俩 个 插件 。 


读 取 Redis 数据 


LogStash::Inputs::Redis 支持 三 种 data type (实际 上 是 redis_type) ， 不 同 
的 数据 类 型 会 导致 实际 采用 不 同 的 Redis 命令 操作 : 


e list => BLPOP 
e channel => SUBSCRIBE 
e pattern channel => PSUBSCRIBE 


注意 到 了 人 么 ? 这 里 面 没 有 GET 命令 ! 


Redis 服务 器 通常 都 是 用 作 NoSQL 数据 库 ， 不 过 logstash 只 是 用 来 做 消息 队列 。 
所 以 me logstash 里 的 Redis 会 撑 爆 你 的 内 存 和 磁盘 。 


配置 示例 


input { 
redis { 
data type => "pattern channel" 
key -» "logstash-*" 
host => "192.168.0.2" 
port => 6379 
threads => 5 


使 用 方式 
基本 方法 


首先 确认 你 设置 的 host 服务 器 上 已 经 运行 了 redis-server 服务 ， 然 后 打开 终端 1 1 
logstash 进程 等 待 输入 数据 ， 然 后 打开 另 一 个 终端 ， 输 入 redis-cli 命令 ( 先 
RAF redis 软件 包 )， 在 交互 式 提示 符 后 面 输入 PUBLISH logstash-demochan 
"hello world" 


# redis-cli 
127.0.0.1:6379» PUBLISH logstash-demochan "hello world" 


你 会 在 第 一 个 终端 里 看 到 logstash 进程 输出 类 似 下 面 这 样 的 内 容 : 


{ 
"message" => "hello world", 
"@version" => "1", 
"@timestamp" => "2014-08-08T16:26:29.399Z" 
} 


注意 : 这 个 事件 里 没有 host 字段 ! (或 许 这 算是 bug...... ) 


输入 JSON 数据 


如 果 你 想 通 过 redis 的 频道 给 logstash 事件 添加 更 多 字段 ， 直 接 向 频道 发 布 JSON 
字符 串 就 可 以 了 。 LogStash::Inputs::Redis 会 直接 把 JSON 转换 成 事件 。 


继续 在 第 二 个 终端 的 交互 式 提示 符 下 输入 如 下 内 容 : 


127.0.0.1:6379> PUBLISH logstash-chan '{"message":"hello world", 
"Qversion":"1","Qtimestamp":"2014-08-08T16:34:21.865Z", host":"r 
aochenlindeMacBook-Air.local", "keyi":"valuei"}' 


你 会 看 到 第 一 个 终端 里 的 logstash 进程 随即 也 返回 新 的 内 容 ， 如 下 所 示 : 


"message" => "hello world", 
"@version" => "1", 
"@timestamp" => "2014-08-09T00:34:21.865+08:00", 
"host" => "raochenlindeMacBook-Air.local", 
"key1" => "valuei" 


看 ， 新 的 字段 出 现 了 ! 现在 ， 你 可 以 要 求 开发 工程 师 直接 向 你 的 redis 频道 发 送信 
息 好 了 ， 一 切 自动 搞定 。 


小 贴 士 


这 里 我 们 建议 的 是 使 用 pattern channel 作为 输入 插件 的 data type 设置 值 。 因 为 
实际 使 用 中 ， 你 的 redis 频道 可 能 有 很 多 不 同 的 keys， 一 般 命名 成 logstash-chan- 
%f{type} 这 样 的 形式 。 这 时 候 pattern channel 类 型 就 可 以 帮助 你 一 次 订阅 全 部 
logstash 相关 频道 | 


扩展 方式 

如 上 段 "小 贴 士 " 提 到 的 ， 之 前 两 个 使 用 场景 采用 了 同样 的 配置 ， 即 数据 类 型 为 频道 
发 布 订 阅 方式 。 这 种 方式 在 需要 扩展 logstash 成 多 节点 集群 的 时 候 ， 会 出 现 一 个 问 
题 : 通过 频道 发 布 的 一 条 信息 ， 会 被 所 有 订阅 了 该 频道 的 logstash 进程 同时 接收 
到 ， 然 后 输出 重复 内 容 ! 

你 可 以 尝试 再 做 一 次 上 面 的 实验 ， 这 次 在 两 个 终端 同时 启动 logstash -f 
redis-input.conf 进程 ， 结 果 会 是 两 个 终端 都 输出 消息 。 

这 种 时 候 ， 就 需要 用 list 类 型 。 在 这 种 类 型 下 ， 数 据 输入 到 redis MARL F > 


logstash 则 连 上 redis 服务 器 取 走 ( BLPOP 命令 ， 所 以 只 要 logstash 不 堵塞 ， 
redis 服务 器 上 也 不 会 有 数据 堆积 占用 空间 ) 数 据 。 


配置 示例 


input { 
redis { 

batch_count => 1 
data_type => "list" 
key => "logstash-list" 
host => "192.168.0.2" 
port => 6379 
threads => 5 


使 用 方式 
这 次 我 们 同时 在 两 个 终端 运行 logstash -f redis-input-list.conf 进程 。 然 


后 在 第 三 个 终端 里 启动 redis-cli 命令 交互 : 


$ redis-cli 
127.0.0.1:6379» RPUSH logstash-list "hello world" 
(integer) 1 

这 时 候 你 可 以 看 到 ， 只 有 一 个 终端 输出 了 结果 。 


连续 RPUSH 几 次 ， 可 以 看 到 两 个 终端 近 于 各 自 输 出 一 半 条 目 。 


小 贴 士 


RPUSH 支持 batch 方式 ， 修 改 logstash 配置 中 的 batch count 值 ， 作 为 示例 
这 里 只 改 到 2， 实 际 运用 中 可 以 更 大 (事实 上 Logstash::Outputs::Redis 对 应 
这 点 的 batch event 配置 默认 值 就 是 50)。 


重启 logstash 进程 后 ，redis-cli 命令 中 改 成 如 下 发 送 : 


127.0.0.1:6379» RPUSH logstash-list "hello world" "hello world" 
"hello world" "hello world" "hello world" "hello world" 
(integer) 3 


可 以 看 到 ， 两 个 终端 也 各 自 输 出 一 部 分 结果 。 而 你 只 用 了 一 次 RPUSH 命令 。 


输出 到 Redis 
配置 示例 


input { stdin {} } 
output { 
redis { 
data_type => "channel" 
key => "logstash-chan-%{+yyyy.MM.dd}" 


使 用 方式 
我 们 还 是 继续 先 用 redis-cli 命令 行 来 演示 outputs/redis 插件 的 实质 。 


基础 方式 


运行 logstash 进程 ， 然 后 另 一 个 终端 启动 redis-cli 命令。 输入 订阅 指定 频道 的 
Redis 命令 a dat logstash-chan-2014.08.08") 后 ， 首 先 会 看 到 一 个 订阅 成 
功 的 返回 信息 。 如 下 所 示 : 


# redis-cli 

127.0.0.1:6379> SUBSCRIBE logstash-chan-2014.08.08 
Reading messages... (press Ctrl-C to quit) 

1) "subscribe" 

2) "logstash-chan-2014.08.08" 

3) (integer) 1 


好 ， 在 运行 logstash 的 终端 里 输入 "hello world" 字符 串 。 切 换 回 redis-cli 的 终端 ， 
你 发 现 已 经 自动 输出 了 一 条 信息 : 


1) "message" 

2) "logstash-chan-2014.08.08" 

3) "{\"message\":\"hello world\", \"@version\":\"1\",\"@timestamp 
\":\"2014-08-08T16:34:21.865Z\", \"host\":\"raochenlindeMacBook-A 
ir.local\"}" 


broker 方式 


上 面 那 条 信息 看 起 来 是 不 是 非常 眼熟 ?这 一 串 字 符 其 实 就 是 我 们 在 前 面 " 读 取 Redis 
中 的 数据 "小 节 中 使 用 的 那 段 数据 。 


看 ， 这 样 就 把 outputs/redis 和 inputs/redis 串联 起 来 了 吧 | 
事实 上 ， 这 就 是 我 们 使 用 redis 服务 器 作为 logstassh 架构 中 broker 角色 的 原理 。 


让 我 们 把 这 两 节 中 不 同 配置 的 logstash 进程 分 别 在 两 个 终端 运行 起 来 ， 这 次 不 再 要 
运行 redis-cli 命令 了 。 在 配 有 outputs/redis 这 端 输入 "hello world"， 配 有 
"inputs/redis" 的 终端 上 ， 就 自动 输出 数据 了 | 


告警 用 途 


我 们 还 可 以 用 其 他 程序 来 订阅 redis 频道 ， 程 序 里 就 可 以 随意 写 其 他 逻辑 了 。 你 可 
以 看 看 output/juggernaut 插件 的 原理 。 这 个 Juggernaut 就 是 基于 redis 服务 器 和 
socket.io 框架 构建 的 。 利 用 它 ，logstash 可 以 直接 向 webkit 等 支持 socket.io 的 浏 


览 器 推送 告警 信息 。 


扩展 方式 


fe LogStash::Inputs::Redis 一 样 ， 这 里 也 有 设置 成 list 的 方式 。 使 用 
RPUSH 命令 发 送 给 redis 服务 器 ， 效 果 和 之 前 展示 的 完全 一 致 。 包 括 可 以 调整 的 
参数 batch event ， 也 在 之 前 章节 中 讲 过 。 这 里 不 再 重复 举例 。 


通过 kafka 传 输 


本 节 作 者 : jingbli 


Kafka 是 一 个 高 吞吐 量 的 分 布 式 发 布 订 阅 日 志 服 务 ， 具 有 高 可 用 、 高 性 能 、 分 布 
式 、 高 扩展 、 持 久 性 等 特性 。 目 前 已 经 在 各 大 公司 中 广泛 使 用 。 和 之 前 采用 Redis 
做 轻 量 级 消息 队列 不 同 ，Kafka 利用 磁盘 作 队 列 ， 所 以 也 就 无 所 谓 消 息 缓 冲 时 的 磁 
盘问 题 。 此 外 ， 如 果 公 司 内 部 已 有 Kafka 服务 在 运行 ，logstash 也 可 以 快速 接 入 ， 
免 去 重复 建设 的 麻烦 。 


如 果 打 算 新 建 Kafka 系统 的 ， 请 参考 Kafka 官方 入 门 文 
档 : http://kafka.apache.org/documentation.html#quickstart 


kafka 基本 概念 


以 下 仅 对 相关 基本 概念 说 明 ， 更 多 概念 见 官 方 文档 : 


e Topic 主题 ， 声 明 一 个 主题 ，producer 指 定 该 主题 发 布 消息 ， 订 阅 该 主题 的 
consumer 对 该 主题 进行 消费 

e Partition 每 个 主题 可 以 分 为 多 个 分 区 ， 每 个 分 区 对 应 磁盘 上 一 个 目录 ， 分 区 可 
以 分 布 在 不 同 broker 上 ，producer 在 发 布 消息 时 ， 可 以 通过 指定 partition key 
射 到 对 应 分 区 ， 然 后 向 该 分 区 发 布 消息 ， 在 无 partition key 情 况 下 ， 随 机 选取 分 
区 ， 一 段 时 间 内 触发 一 次 (比如 10 分 钟 )， 这 样 就 保证 了 prodneer 同一 
partition 发 布 的 消息 是 顺序 的 。 消 费 者 消费 时 ， 可 以 指定 partition 进 行 消费 ， 也 
可 以 使 用 high-level-consumer api, 自 动 进行 负载 均衡 ， 并 将 partition 分 给 
consumer ， 一 个 partition 只 能 被 一 个 consumer 进 行 消费 。 

e Consumer 消费 者 ， 可 以 多 实例 部 署 ， 可 以 批量 拉 取 ， 有 两 类 API 可 供 选择 : 
一 个 simpleConsumer， 骏 露 所 有 的 操作 给 用 户 ， 可 以 提交 offset、fetch 
offset、 指 定 partition fetch message ; 另外 一 个 high-level- 
consumer(ZookeeperConsumerConnector) > # 3) A P & X T partition | a> 
配 的 负载 均衡 ， 定 期 提交 offset， 建 立 消费 队列 等 。simpleConsumer 相 当 于 手 
动 挡 ，high-level-consumer 相 当 于 自动 挡 。 


simpleConsumer : 无 需 像 high-level-consumer 那 样 向 zk 注册 brokerid、 
OWner， 甚 至 不 需要 提交 offset 到 zk， 可 以 将 offset 提 交 到 任意 地 方 比如 (mysql， 
本 地 文件 等 )。 


high-level-consumer : 一 个 进程 中 可 以 启 多 个 消费 线程 ， 一 个 消费 线程 即 是 一 
个 consumer， 假 设 A 进程 里 有 2 个 线程 (consumerid 分 别 为 1，2)，B 进 程 有 2 个 
AX f£(consumerid2" 9! 7j 1 > 2) > topic 27 partition 54* > 7$ Z partition" &c z& 3x 
样 的 : 


partition1 ---> A 进程 consumerid1 
partition2 ---» A 进程 consumerid1 
partition3 ---> A 进程 consumerid2 
partition4 ---> B 进 程 consumer1 
partition5 ---> B 进 程 consumer2 


e Group High-level-consumer 可 以 声明 group， 每 个 group 可 以 有 多 个 
consumer， 每 group 各 自 管理 各 自 的 消费 offset， 各 个 不 同 group 之 问 互 不 关联 


影响 。 


由 于 目前 版 本 消费 的 offset、owner、group 都 是 consumer 自 己 通过 zk 管理 ， 所 
以 group 对 于 broker 和 producer 并 不 关心 ， 一 些 监 控 工 具 需 要 通过 group 来 监 
控 ，simpleComsumer 无 需 声 明 group。 


小 提示 


以 上 概念 是 logstash 的 kafka 插件 的 必要 参数 ， 请 理解 阅读 ， 对 后 续 使 用 kafka 插 
件 有 重要 作用 。logstash-kafka-input 插件 使 用 的 是 High-level-consumer 
API e 


插件 安装 


logstash-1.4 安装 


如 果 你 使 用 的 还 是 1.4 版 本 ， 需 要 自己 单独 安装 logstash-kafka 插件 。 插 件 地 址 
JL : https://github.com/joekiller/logstash-kafka ° 


插件 本 身 内 容 非 常 简单， 其 主要 依赖 同一 作者 写 的 jruby-kafka 模块 。 需 要 注意 的 


是 : 该 模块 仅 支持 Kafka-0.8 版 本 。 如 果 是 使 用 0.7 版 本 kafka 的 ， 将 无 法 直接 使 
jruby-kafka 该 模块 和 logstash-kafka 插件 。 


装 按照 官方 文档 完全 自动 化 的 安装 。 或 是 可 以 通过 以 下 方式 手动 自己 安装 插件 ， 
不 过 重点 注意 的 是 kafka 的 版 本 ， 上 面 已 经 指出 了 。 


省 


1. FA logstash 并 解压 重 命名 为 ./logstash-1.4.0 文件 目录 。 
2. 下 载 kafka 相关 组 件 ， 以 下 示例 选 的 为 kafka 2.8.0-0.8.1.1-src， 并 解压 重 命 
名 为 ./kafka 2.8.0-0.8.1.1 » 
3. 从 releases X F logstash-kafka v0.4.2 版 ， 并 解压 重 命名 为 ”,/logstash- 
kafka-0.4.2 ° 
4. 从 ./kafka_2.8.0-0.8.1.1/libs 目录 下 复制 所 有 的 jar 文件 拷贝 到 
./logstash-1.4.0/vendor/jar/kafka_2.8.0-0.8.1.1/libs 下 ， 其 中 你 
需要 创建 kafka_2.8.0-0.8.1.1/libs 相关 文件 夹 及 目录 。 
5. 分 别 复 制 ./logstash-kafka-0.4.2/1ogstash 里 的 inputs 和 
outputs 下 的 kafka.rb ， 拷 贝 到 对 应 的 ./logstash- 
1.4.0/lib/logstash 里 的 inputs 和 outputs 对 应 目录 下 。 
6. 切换 到 ./logstash-1.4.0 目录 下 ， 现 在 需要 运行 e -kafka 的 
gembag.rb 脚本 去 安装 jruby-kafka 库 ， 执 行 以 下 命 
GEM_HOME=vendor/bundle/jruby/1.9 GEM_PATH= java -jar 
vendor/jar/jruby-complete-1.7.11.jar --1.9 ../logstash-kafka- 
0.4.2/gembag.rb ../logstash-kafka-0.4.2/logstash- 
kafka.gemspec ° 
7. 现在 可 以 使 用 logstash-kafka 插件 运行 logstash 了 。 


logstash-1.5 安装 


logstash 从 1.5 版 本 开始 才 集 成 了 Kafka 支持 。1.5 版 本 开始 所 有 插件 的 目录 和 命 
名 都 发 生 了 改变 ， 插 件 发 布地 址 见 : https://github.com/logstash-plugins ° 安装 和 
更 新 插件 都 可 以 使 用 官方 提供 的 方式 : 


$bin/plugin install OR $bin/plugin update 


小 贴 士 


对 于 插件 的 安装 和 更 新 ， 默 认 走 的 Gem 源 为 https://rubygems.org, 对 于 咱们 国内 网 

络 来 说 是 出 奇 的 慢 或 是 根本 无 法 访问 RFR) ， 在 安装 或 是 更 新 插件 是 ， 可 
以 尝试 修改 目录 下 Gemfile 文件 中 的 source 为 淘宝 源 

https://ruby.taobao.org， 这 样 会 使 你 的 安装 或 是 更 新 顺畅 很 多 。 


插件 配置 


Input 配置 示例 
以 下 配置 可 以 实现 对 kafka 读 取 端 (consumer) 的 基本 使 用 。 


消费 端 更 多 详细 的 配置 请 查看 
http://kafka.apache.org/documentation.html#consumerconfigs kafka 官方 文档 的 消 
费 者 部 分 配置 文档 。 


input { 
kafka { 
zk_connect => "localhost:2181" 
group_id => "logstash" 
topic_id => "test" 
codec => plain 
reset beginning => false # boolean (optional): default: 


false 
consumer threads => 5 # number (optional)’ default: 1 
decorate events => true # boolean (optional)’ default: 
false 
} 
} 


Input 解释 


TE A Consumer 端 ,插件 使 用 的 是 High-level-consumer API ， 请 结合 上 述 
kafka 基本 概念 进行 设置 : 
e group id 


消费 者 分 组 ， 可 以 通过 组 ID 去 指定 ， 不 同 的 组 之 间 消 费 是 相互 不 受 影响 的 ， 相 互 


e topic_id 


A8 CH IEA Wes A > 48 EG wR topic ， 这 个 其 实 就 是 订阅 某 个 主 
题 ， 然 后 去 消费 。 


e reset_beginning 


logstash 局 动 后 从 什么 位 置 开 始 读 取 数 据 ， 黑 认 是 结束 位 置 ， 也 就 是 说 进 
2 2 RE anode. 开始 继续 读 取 ， 如 果 之 前 没有 消费 过 ， 那 么 就 开 
始 从 头 读 取 . 如 果 你 是 要 导入 原 有 数据 ， 把 这 个 设 定 改 成 "true"，logstash 进 a 就 从 
头 开 始 读 取 . 有 点 类 似 cat ， 但 是 读 到 最 后 一 行 不 会 终止 ， 而 是 变 成 tail -F 

， 继续 监听 相应 数据 。 


e decorate_events 


在 输出 消息 的 时 候 会 输出 自身 的 信息 包括 :消费 消息 的 大 小 ，topic 来 源 以 及 
consumer 的 group 信息 。 


e rebalance_max_retries 


当 有 新 的 consumer(logstash) 加 入 到 同一 group 时 ， 将 会 reblance ， 此 后 将 会 
有 partitions 的 消费 端 迁 移 到 新 的 consumer 上 ， 如 果 一 个 consumer 获 
得 了 某 个 partition 的 消费 权限 ， 那 么 它 将 会 向 zookeeper 注册 ， 
Partition Owner registry 节点 信息 ， 但 是 有 可 能 此 时 旧 的 consumer 尚 没 
有 释放 此 节点 ， 此 值 用 于 控制 ， 注 册 节 点 的 重 试 次 数 。 


e consumer_timeout_ms 
指定 时 间 内 没有 消息 到 达 就 抛 出 异常 ， 一 般 不 需要 改 。 


以 上 是 相对 重要 参数 的 使 用 示例 ， 更 多 参数 可 以 选项 可 以 跟 据 
https://github.com/joekiller/logstash-kafka/blob/master/README.md 查看 input & 
认 参 数 。 


ERS 


n 想 要 使 用 多 个 logstash 端 协同 消费 同一 个 topic 的 话 ， 那么 需要 把 两 个 或 是 

个 logstash 消费 端 配置 成 相同 的 Seps id 和 topic id ， 但 是 前 提 是 要 把 
的 topic 分 多 个 partitions (区 )， 多 个 消费 者 消费 是 无 法 保证 消息 的 消费 顺序 
性 的 。 


这 里 解释 下 ， 为 什么 要 分 多 个 partitions( 区 ) * kafka 的 消息 模型 是 对 topic 分 
区 以 达到 分 布 式 效果 。 每 个 topic 下 的 不 同 的 partitions (区 ) 只 能 有 一 个 
Owner 去 消费 。 所 以 只 有 多 个 分 区 后 才能 启动 多 个 消费 者 ， 对 应 不 同 的 区 去 消 
费 。 其 中 协调 消费 部 分 是 由 server 端 协 调 而 成 。 不 必 使 用 者 考虑 太 多 。 只 是 消 
息 的 消费 则 是 无 序 的 。 


总 结 : 保 证 消息 的 顺序 ， 那 就 用 一 个 partition 。 kafka 的 每 个 partition 只 能 同时 被 
同一 个 group 中 的 一 个 consumer 消费 。 


Output 配置 


以 下 配置 可 以 实现 对 kafka 写 入 端 (producer) 的 基本 使 用 。 


生产 端 更 多 详细 的 配置 请 查看 
http://kafka.apache.org/documentation.html#producerconfigs kafka 官方 文档 的 生 
产 者 部 分 配置 文档 。 


output { 
kafka { 
bootstrap_servers => "localhost:9092" 
topic_id => "test" 
compression codec => "snappy" # string (optional)* one 
of ["none"* "gzip"* "snappy"]* default: "none" 


} 


Output 解释 


作为 Producer 端 使 用 ， 以 下 仅 为 重要 概念 解释 ， 请 结合 上 述 kafka 基本 概念 进行 


设置 : 
e compression_codec 


消息 的 压缩 模式 ， 默 认 是 none， 可 以 有 gzip 和 snappy (暂时 还 未 测试 开局 压 线 
开启 的 性 能 ， 数 据 传 输 大 小 等 对 比 )。 


my 
Jv 


e compressed topics 


可 以 针对 特定 的 topic 进行 压缩 ， 设 置 这 个 参数 为 topic ， 表 示 此 topic 3 
压缩 。 


— 


e request required acks 


消息 的 确认 模式 : 


可 以 设置 为 0: 生产 者 不 等 待 broker 的 回应 ， 只 管 发 送 .会 有 最 低能 的 延迟 和 最 
差 的 保证 性 (在 服务 器 失败 后 会 导致 信息 丢失 ) 可 以 设置 为 1: 生产 者 会 收 到 
leader 的 回应 在 leader 写 入 之 后 .( 在 当前 leader 服务 器 为 复制 前 失败 可 能 会 导 
致 信息 丢失 ) 可 以 设置 为 -1: 生产 者 会 收 到 leader 的 回应 在 全 部 拷贝 完成 之 
2E 


e partitioner_class 
分 区 的 策略 ， 默 认 是 hash SU 
e send_buffer_bytes 


socket 的 缓存 大 小 设置 ， 其 实 就 是 缓冲 区 的 大 小 


消息 模式 相关 
e serializer_class 


消息 体 的 系列 化 处 理 类 ， 转 化 为 字 节 流 进行 传输 ， 请 注意 encoder 必须 和 下 面 的 
key_serializer_class 使 用 相同 的 类 型 。 


e key_serializer_class 
默认 的 是 与 serializer_class 相同 
e producer type 
生产 者 的 类 型 async 异步 执行 消息 的 发 送 sync 同步 执行 消息 的 发 送 
e queue_buffering max_ms 
异步 模式 下 ， 那 么 就 会 在 设置 的 时 间 缓 存 消息 ， 并 一 次 性 发 送 
e queue_buffering max_messages 
异步 的 模式 下 ， 最 长 等 待 的 消息 数 
e queue enqueue timeout ms 


异步 模式 下 ， 进 入 队列 的 等 待 时 间 ， 若 是 设置 为 0， 那 么 要 么 进入 队列 ， 要 么 直接 
抛弃 


e batch_num_messages 


异步 模式 下 ， 每 次 发 送 的 最 大 消息 数 ， 前 提 是 触发 了 


queue buffering max messages 或 是 queue enqueue timeout ms 的 限制 


以 上 是 相对 重要 参数 的 使 用 示例 ， 更 多 参数 可 以 选项 可 以 跟 据 
https://github.com/joekiller/logstash-kafka/blob/master/README.md 查看 output 
默认 参数 。 


小 贴 士 


logstash-kafka 插件 输入 和 输出 默认 codec AW json 格式 。 在 输入 和 输出 的 时 候 
注意 下 编码 格式 。 消 息 传递 过 程 中 logstash 默认 会 为 消息 编码 内 加 入 相应 的 时 间 和 戳 
和 hostname 等 信息 。 如 果 不 想 要 以 上 信息 (一 般 做 消息 转发 的 情况 下 )， 可 以 使 用 
以 下 配置 ， 例 如 : 


output { 
kafka { 
codec => plain { 
format => "%{message}" 


作为 Consumer 从 kafka 中 读数 据 ， 如 果 为 非 json 格式 的 话 需要 进行 相关 解码 ， 例 
Je : 


input { 
kafka { 
zk connect => "xxx: xxx" 
group id -» "test" 
topic id -» "test-topic" 
codec -» "line" 
} 
} 


队列 监控 
其 实 logstash 的 kafka 插件 性 能 并 不 是 很 突出 ， 可 以 通过 使 用 以 下 命令 查看 队列 积 
压 消费 情况 : 


$/bin/kafka-run-class.sh kafka.tools.ConsumerOffsetChecker --gro 
up test 


队列 积压 严重 ， 性 能 跟 不 上 的 情况 下 ， 结 合 实际 服务 器 资源 ， 可 以 适当 增加 topic 
的 partition 多 实例 化 Consumer 进行 消费 处 理 消 息 。 


input-kafka 的 JSON 序列 化 性 能 


此 外 ， 跟 logstash-input-syslog 改 在 filter 阶段 grok 的 优化 手段 类 似 ， 也 可 以 将 
logstash-input-kafka 的 默认 JSON 序列 化 操作 从 codec 阶段 后 移 到 filter 阶段 。 如 
y 


input { 
kafka { 
codec => plain 
} 
} 
filter { 
json { 
source => "message" 
J 
} 


然后 通过 bin/logstash -w $num_cpus 运行 ， 利 用 多 核 计算 优势 ， 可 以 获得 大 
约 一 倍 左右 的 性 能 提升 。 
其 他 方案 


e https://github.com/reachkrishnaraj/kafka-elasticsearch-standalone-consumer 
e https://github.com/childe/hangout 
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AIX 平台 上 的 Logstash-Forwarder-Java 


本 节 作 者 : 觅 程 


在 AIX 环 境 下 (IBM Power 小 型 机 的 一 种 操作 系统 ) ,你 无 法 使 用 logstash (因为 IBM 
JDK 没 有 实现 相关 方法 ) ， 也 无 法 使 用 logstash-forwarder ，github 上 有 个 Logstash- 
forwarder 再 实现 的 项 目 就 是 解决 这 个 问题 的 : https://github.com/didfet/logstash- 
forwarder-java 


配置 和 Logstash-forwarder 基 本 一 致 ， 但 是 注意 有 一 个 坑 是 需要 关注 的 ， 作 者 也 在 
他 的 github 上 提 到 了 ， 就 是 : 


the ssl ca parameter points to a java keystore containing the ro 
ot certificate of the server, not a PEM file 


不 熟悉 证 书 相关 体系 的 读者 可 能 不 太 清 楚 这 个 意思 ， 换 句 话 说， 如 果 你 还 按照 
logstash-forwarder 的 配置 方法 配置 shipper 端 ， 那 么 你 将 会 得 到 一 个 诡 央 的 
java.io.|OException: Invalid keystore format 异常 


首先 介绍 下 背景 知识 ， 摘 录 一 段 知 乎 上 的 讲解 : @ Kt from 
http://www.zhihu.com/question/29620953 


把 SSL 系 统 比 喻 为 工商 局 系统 。 首 先 有 SSL 就 有 CA，certificate authority ° 证 
书局 ， 用 于 制作 、 认 证 证 书 的 第 三 方 机 构 ， 我 们 假设 营业 执照 非常 难 制作 ， 就 
像 身 份 证 一 样 ， 需 要 有 制 证 公司 来 提供 ， 并 且 提 供 技术 帮助 工商 局 验证 执照 的 
监 伪 。 然 后 CA 是 可 以 有 多 个 的 ， dM i 证 公司 ， 但 工商 局 就 只 有 
一 个 ， 它 来 说 那个 制 证 公司 是 可 信 的 ， 159» 需要 打击 。 在 SSL 的 世界 
中 ， 微 软 、Google 和 Mozilla 扮 演 了 一 部 分 ‘oF 色 。 也 就 是 说 ，IE、 
Chrome、Firefox 中 内 置 有 一 些 CA， 经 过 这 些 CA 和 颁发， 验证 过 的 证 书 都 是 可 以 
信 的 ， 和 否则 就 会 提示 你 不 安全 。 这 也 是 为 什么 前 几 天 Chrome 决 定 屏 蔽 CNNIC 
的 CA 时 ，CNNIC 那 么 遗憾 了 。 也 因为 内 置 的 CA 是 相对 国定 的 ， 所 以 当 你 决定 
要 新 建 网 站 时 ， 就 需要 购买 这 些 内置 CA 颁 发 的 证 书 来 让 用 户 看 到 你 的 域名 前 面 
是 绿色 的 ， 而 不 是 红色 。 而 这 个 最 大 的 卖 证 书 的 公司 就 是 VeriSign 如 果 你 听 说 
过 的 话 ， 当 然 它 被 卖 给 了 Symantec， 这 家 伙 不 只 出 Ghost， 还 是 个 卖 证 书 的 公 
ü e 


AIX 平台 上 的 logstash-forwarder-java 


要 开店 的 老板 去 申请 营业 执照 的 时 候 是 需要 交 他 的 身份 证 的 ， 然 后 办 出 来 的 营 
业 执 照 上 也 会 有 他 的 照片 和 名 字 。 身 份 证 相当 于 私 铀 ， 营 业 执 照 就 是 证 书 ， 
Ceritficate > .cer X 4#} ° 


然后 关于 私 钥 和 公 钥 如 何 解 释 我 没 想 好 ， 而 它们 在 数据 加 密 层 面 ， 数 据 的 流向 
是 这 样 的 。 


消息 -->[ 公 铀 ]--> 加 密 后 的 信息 -->[ 私 铀 ]--> 消 息 


公 负 是 可 以 随便 扔 给 谁 的 ， 他 把 消息 加 了 密 传 给 我 。 对 了 ， 可 以 这 样 理 解 ， 我 
有 一 个 箱子 ， 一 把 锁 和 一 把 钥 是 ， 我 把 箱子 和 开 着 的 锁 给 别人 ， 他 写 了 信 放 箱 
子 里 ， 锁 上 ， 然 后 传递 回 我 手 上 的 途中 谁 都 是 打 不 开 箱 子 的 ， 只 有 我 可 以 用 原 
来 的 钥匙 打开 ， 这 就 是 SSL， 公 钥 ， 私 钥 传 递 加 密 消 息 的 方式 。 这 里 的 密 钥 就 
是 key 文 件 。 


于 是 我 们 就 有 了 .cer 和 .key 文 件 。 接 下 来 说 keystore 


不 同 的 语言 、 工 具 序列 SSL 相 关 文 件 的 格式 和 扩展 名 是 不 一 样 的 。 其 中 Java 系 
喜欢 用 keystore, truststore 来 和 干洗， 你 看 它 的 名 字 ，Store， 人 仓库， 它 里 面 存放 
着 key 和 信任 的 CA，key 和 CA 可 以 有 多 个 。 这 里 的 truststore 就 像 你 自己 电脑 的 
证 书 管理 器 一 样 ， 如 果 你 打开 Chrome 的 设置 ， 找 到 HTTP SSL， 就 可 以 看 到 里 
面 有 很 多 CA，truststore 就 是 干 这 个 活 儿 的 ， 它 也 里 面 也 是 存 一 个 或 多 个 CA 让 
Tomcat 或 Java 程 序 来 调用 。 而 keystore 就 是 用 来 存 密 钥 文件 的 ， 可 以 存放 多 


| o 


然后 是 PEM， 它 是 由 RFC1421 至 1424 定 义 的 一 种 数据 格式 。 其 实 前 面 的 .cert 
和 .key 文 件 都 是 PEM 格 式 的 ， 只 不 过 在 有 些 系统 中 (比如 Windows) 会 根据 扩 
展 名 不 同 而 做 不 同 的 事 。 所 以 当 你 看 到 .pem 文 件 时 ， 它 里 面 的 内 容 可 能 是 
certificate 也 可 能 是 key， 也 可 能 两 个 都 有 ， 要 看 具体 情况 。 可 以 通过 openssl 查 
= 


AB xU HL HE T > #2 Blogstash-forwarder-javasy JE Zi TE > 36s] dk 63 
shipper ssl ca 这 个 域 配置 的 应 该 是 keystore， 而 不 是 PEM， 因 此 需要 从 你 生成 的 
crt 中 创建 出 keystore (jks) 文件 ， 方 法 为 : 


keytool -importcert -trustcacerts -file logstash-forwarder.crt - 
alias ca -keystore keystore.jks 


一 个 示例 的 shipper.conf 为 : 
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"network": ( 
"servers": [ "192.168.1.1:5043"], 
"ssl ca": "/mnt/diski2/logger/logstash/config/keystore.jks" 


ty 
"files": [ 
{ 
"paths": [ "/mnt/disk12/logger/logstash/config/2.txt" ], 
"fields": { "type": "sadb" } 
} 
] 


注意 : Server 可 以 配置 多 个 ， 这 样 agent 如 果 一 个 /logstash 连 接 不 上 可 以 连接 另外 


其 余 配 置信 息 ， 请 参考 logstash-forwarder， 它 完全 兼容 。 主 要 包括 下 面 几 个 可 用 配 


2, 


e network.servers: 用 来 指定 远 端 ( 即 logstash indexer 角色 ) 服 务 器 的 IP 地 址 和 
端口 。 这 里 可 以 写 数 组 ， 但 是 logstash-forwarder 只 会 随机 选 一 台 作 为 对 端 发 
送 数据 ， 一 直到 对 端 故障 ， 才 会 重 选 其 他 服务 器 。 

e network.ssl*: 网 络 交互 中 使 用 的 SSL 证 书 路 径 。 

e files.*.paths: 读 取 的 文件 路 径 。 logstash-forwarder 只 支持 两 种 输入 ， 一 种 就 
是 示例 中 用 的 文件 方式 ， 和 logstash 一 样 也 支持 glob 路 径 ， 即 

"/var/log/*.log" 这 样 的 写法 ; 一 种 是 标准 输入 ， 写 法 为 "paths": [ 


non ] 
e files.*.fields: 给 每 条 日 志 添 加 的 固定 字段 ， 相 当 于 logstash 2% add field 
参数 。 


配置 好 以 后 启动 它 即 可 : nohup java -jar logstash-forwarder-java-0.2.3- 
SNAPSHOT. jar -quiet -config logforwarder.conf > logforwarder.log & 


-quiet 参数 可 以 大 大 减少 不 必要 的 日 志 量 ， 如 果 遇 到 错误 请 打开 -debug 和 -trace 选 
项 ， 得 到 相关 信息 后 查证 ， 未 果 时 请 转向 该 项 目 gjithub 的 jissue 区 ， 作 者 很 热心 


测试 通过 环境 : 


e AIX 版 本 


AIX 平台 上 的 logstash-forwarder-java 


6100-04-06-1034 


e Java 版 本 


java version "1.6.0" Java(TM) SE Runtime Environment (build 
pap6460sr14-20130705_01(SR14)) IBM J9 VM (build 2.4, JRE 1.6.0 IBM 
J9 2.4 AIX ppc64-64 jvmap6460sr14-20130704 155156 (JIT enabled, 
AOT enabled) J9VM - 20130704 155156 JIT - r9 20130517 38390 GC - 
GA24 Java6 SR14 20130704 1138 B155156) JCL - 20130618 01 
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Rsyslog 


Rsyslog 是 RHEL6 开始 的 默认 系统 syslog 应 用 软件 (当然 ，RHEL 自 带 的 版 本 较 
低 ， 实 际 官方 稳定 版 本 已 经 到 v8 了 )。 官 网 地 址 http://www.rsyslog.com 


目前 Rsyslog 本 身 也 支持 多 种 输入 输出 方式 ， 内 部 逻辑 判断 和 模板 处 理 。 


常用 模块 介绍 


ESOS 


o e 















P 
sel 


hiredis 铭 redis 
snmp 

libdbi è 

ran 

a 


mysql ie 
zmq3 @MQ 


不 同 模块 插件 在 rsyslog 流程 中 发 挥 作用 的 原理 ， 可 以 阅 
i& : http://www.rsyslog.com/doc/master/configuration/modules/workflow.html 


流程 中 可 以 使 用 mmnormalize 组 件 来 完成 数据 的 切 分 (相当 于 logstash 的 


filters/grok 功能 )。 


rsyslog 从 v7 版 本 开始 带 有 omelasticsearch 插件 可 以 直接 写 入 数据 到 
elasticsearch 集群 ， 配 合 mmnormalize 的 使 用 示例 见 : 
http://puppetlabs.com/blog/use-rsyslog-and-elasticsearch-powerful-log- 
aggregation 


而 normalize 语法 说 明 见 : http://www.liblognorm.com/files/manual/index.html? 
sampledatabase.htm 


类 似 的 还 有 mmfields 和 mmjsonparse 2144 » i£ € > mmjsonparse 要 求 被 解析 的 
MSG 必须 以 QcEE: 开头 ， 解 析 之 后 的 字符 串 为 JSON。 使 用 示例 

见 :http://blog.sematext.com/2013/05/28/structured-logging-with-rsyslog-and- 
elasticsearch/ 


此 外 ，rsyslog M v6 版 本 开始 ， 设 计 了 一 套 rainerscript 作为 配置 中 的 DSL。 利 用 
rainerscript 中 的 函数 ， 也 可 以 做 到 一 些 数据 解析 和 逮 辑 判断 : 


e tolower 

e cstr 

e cnum 

e wrap 

e replace 

e field 

e re extract 
e re match 
e contains 
e if-else 

e foreach 

e lookup 

e set/reset/unset 


详细 说 明 见 : http://www.rsyslog.com/doc/v8-stable/rainerscript/functions.html 


rsyslog 与 logstash 合作 


虽然 Rsyslog 很 早 就 支持 直接 输出 数据 给 elasticsearch， 但 如 果 你 使 用 的 是 v8.4 
以 下 的 版 本 ， 我 们 这 里 并 不 推荐 这 种 方式 。 因 为 normalize 语法 还 是 比较 简单 ， 只 
支持 时 间 ， 字 符 束 ， 数 字 ，ip 地 址 等 几 种 。 在 复杂 条 件 下 远 比 不 上 完整 的 正则 引 


那么 ， 怎 么 使 用 rsyslog 作为 日 志 收集 和 传输 组 件 ， 来 配合 logstash 工作 呢 ? 


如 果 只 是 简单 的 syslog 数据， 直接 单个 logstash 运行 即 可 ， 配 置 方 式 见 本 书 2.4 
章节 。 


如 果 你 运行 着 一 个 高 负荷 运行 的 rsyslog 系统 ， 每 秒 传输 的 数据 远大 过 单个 
logstash 能 处 理 的 能 力 ， 你 可 以 运行 多 个 logstash 在 多 个 端口 ， 然 后 让 rsyslog 做 
轮训 转发 (事实 上 ， 单 个 omfwd 本 身 的 转发 能 力也 有 限 ， 所 以 推荐 这 种 做 法 ) : 


Ruleset( name="forwardRuleSet" ) { 
Action ( type="mmsequence" mode="instance" from="0" to="4" v 
ar="$.seq" ) 
if $.seq == "0" then { 
action (type="omfwd" Target="127.0.0.1" Port="5140" Pro 
tocol-"tcp" queue.size="150000" queue. dequeuebatchsize="2000" ) 
} 
if $.seq == "1" then { 
action (type="omfwd" Target="127.0.0.1" Port="5141" Pro 
tocol-"tcp" queue.size="150000" queue .dequeuebatchsize="2000" ) 
} 
if $.seq == "2" then { 
action (type="omfwd" Target="127.0.0.1" Port="5142" Pro 
tocol-"tcp" queue.size="150000" queue.dequeuebatchsize="2000" ) 
} 
if $.seq == "3" then { 
action (type="omfwd" Target="127.0.0.1" Port="5143" Pro 
tocol-"tcp" queue.size="150000" queue .dequeuebatchsize="2000" ) 


} 


如 果 rsyslog 仅 是 作为 shipper 角色 运行 ， 环 境 中 有 单独 的 消息 队列 可 用 ，rsyslog 
也 有 对 应 的 omkafka, omredis, omzmq 插件 可 用 。 


rsyslog v8 版 的 mmexternal 模块 
如 果 你 使 用 的 是 v8.4 及 以 上 版 本 的 rsyslog， 其 中 有 一 个 新 加 入 的 mmexternal 模 


块 。 该 模块 是 在 v7 的 omprog 模块 基础 上 发 展 出 来 的 ， 可 以 让 你 使 用 任意 脚本 ， 
接收 标准 输入 ， 自 行 处 理 以 后 再 输出 回来 ， 而 rsyslog 接收 到 这 个 输出 再 进行 下 一 


步 处 理 ， 这 就 解决 了 前 面 提 到 的 “normalize 语法 大 简单 "的 问题 ! 


下 面 是 使 用 rsyslog 的 mmexternal 和 omelasticsearch 完成 Nginx 访问 日 志 直 接 解 
析 存 储 的 配置 。 


rsyslog 配置 如 下 : 


module(load="imuxsock" SysSock.RateLimit.Interval="0") 
module(load="mmexternal" ) 
module(load="omelasticsearch" ) 
template(name="logstash-index" type="list") { 
constant (value="logstash-") 
property(name="timereported" dateFormat="rfc3339" position. f 
rom="1" position. to="4") 
constant (value=".") 
property(name="timereported" dateFormat="rfc3339" position. f 
rom="6" position. to="7") 
constant (value=".") 
property(name="timereported" dateFormat="rfc3339" position. f 
rom="9" position. to="10") 
j 
template( name="nginx-log" type="string" string="%msg%\n" ) 
if ( $syslogfacility-text == 'local6' and $programname startswit 
h 'wb-www-access-' and not ($msg contains '/2/remind/unread coun 
t' or $msg contains '/2/remind/group unread') ) then 
{ 
action( type="mmexternal" binary="/usr/local/bin/rsyslog-ngi 
nx-elasticsearch.py" interface.input="fulljson" forcesingleinsta 
nce="on" ) 
action( type="omelasticsearch" 
template-"nginx-log" 
server="eshost.example.com" 
bulkmode="on" 
dynSearchIndex="on" 
searchIndex="logstash- index" 
searchType="nginxaccess" 
queue. type="linkedlist" 
queue. sSize="50000" 
queue. dequeuebatchsize="5000" 
queue. dequeues Lowdown="100000" 


stop 


其 中 调用 的 python 脚本 示例 如 下 (注意 只 是 做 示例 ， 脚 本 中 的 split 功能 其 实 可 以 用 
rsyslog 的 mmfields 插件 完成 ) : 


#! /usr/bin/python 
import sys 

import json 

import datetime 


def nginxLog(data): 
hostname = data['hostname'] 
logline = data['msg' ] 
time local, http x up calling line id, request, http user ag 
ent, staTus, remote addr, http x log uid, http referer, request 
time, body bytes sent, http x forwarded proto, http x forwarded 
for, request uid, http host, http cookie, upstream response time 
= logline.split(''') 
Eny: 
upstream_response_time = float(upstream_response_time) 
except: 
upstream_response_time = None 


method, uri, verb = request.split(' ') 
arg = {} 
Erny: 
url_path, url_args = uri.split('?') 
for args in url_args.split('&'): 
k, v = args.split('=') 
arg[k] = v 
except: 
url_path = uri 


# Why %z do not implement? 
ret = { 
"@timestamp": datetime.datetime.strptime(time_local, ' [ 
?6d /96b /96Y :%H:%M:%S +0800]').strftime('%FT%T+0800'), 
"host": hostname, 
"method": method.lstrip('"'), 
"url_path": url_path, 
"url_args": arg, 
"verb": verb.rstrip('"'), 
"http_x_up_calling_line_id": http_x_up_calling_line_id, 
"http_user_agent": http_user_agent, 


def 


def 


def 


"status": int(staTus), 

"remote addr": remote addr.strip('[]'), 
"http x leg ud = http =x log urd, 

"http referer": http referer, 

"request time": float(request time), 

"body bytes sent": int(body bytes sent), 

"http x forwarded proto": http x forwarded proto, 
"http x forwarded for": http x forwarded for, 
"request uid": request uid, 

"http_host": http host, 

"http_cookie": http_cookie, 
"upstream_response_time": upstream_response_time 


} 


return ret 


image 人 大 
""" Do everything that is needed to initialize processing 


onReceive(msg): 

data = json.loads(msg) 

ret = nginxLog(data) 

print json.dumps({'msg': ret}) 


onExxt(): 
""" Do everything that is needed to finish processing. This 


is being called immediately before exiting. 


# most often, nothing to do here 


onInit() 
keepRunning = 1 


while keepRunning == 


msg = sys.stdin.readline() 
if msg: 
msg = msg[:len(msg) -1] 
onReceive(msg) 
sys.stdout.flush() 
else: 
keepRunning = 0 


onExit() 
sys.stdout.flush() 


注意 输出 的 时 候 ， 顶 层 的 key 是 不 能 变 的 ，msg 还 得 叫 msg’ 4» hostname 还 
得 叫 hostname > 4° SI > rsyslog 会 当做 处 理 无 效 ， 直 接 传递 原 有 数据 内 容 给 
下 一 步 。 


惯用 提示 


mmexternal 是 基于 direct mode 的 ， 所 以 如 果 你 发 送 的 数据 量 较 大 时 ，rsyslog 并 
不 会 像 linkedlist mode 那样 缓冲 在 磁盘 队列 上 ， 而 是 持续 fork 出 新 的 
mmexternal 程序 ， 几 千 个 进程 后 ， 你 的 服务 器 就 挂 了 1! | 所 以 ， 务 必 开 局 


forcesingleinstance 选项 。 


rsyslog 的 mmgrok 模块 


Rsyslog 8.15.0 开始 ， 附 带 了 mmgrok 模块 ， 系 笔者 贡献 。 利 用 该 模块 ， 可 以 将 
Logstash 的 Grok 规则 ， 运 用 在 Rsyslog 中 。 欢 迎 有 兴趣 的 读者 试用 。 


nxlog 


本 节 作 者 : 松涛 


nxlog 是 用 C 语言 写 的 一 个 跨 平 台 日 志 收 集 处 理 软件 。 其 内 部 支持 使 用 Perl 正则 和 
语法 来 进行 数据 结构 化 和 逮 辑 判断 操作 。 不 过 ， 其 最 常用 的 场景 。 是 在 windows Ak 
务 器 上 ， 作 为 logstash 的 替代 品 运行 。 


nxlog 的 windows 安装 文件 下 载 url JL 
Se eee ET T ee 


配置 


Nxlog 默 认 配 置 文件 位 置 在 : C:\Program Files (x86)\nxlog ° 


配置 文件 中 有 3 个 关键 设置 ， 分 别 是 input (日 志 输 入 端 ) ^ output (日 志 输 出 
端 ) ^route ( 绑 定 某 输 入 到 具体 某 输 出 ) 。。 


例子 
假设 我 们 有 两 台 服 务 器 ， 收 集 其 中 的 windows 事务 日 志 : 


e |logstash 服 务 器 ip 地 址 : 192.168.1.100 
e Windows 测 试 服务 器 ip 地 址 : 192.168.1.101 


收集 流程 : 


1. nxlog 使 用 模块 im_file 收集 日 志文 件 ， 开 启 位 置 记录 功能 
2. nxlog 使 用 模块 tcp 输 出 日 志 
3. logstash 使 用 input/tcp ， 收 集 日 志 ， 输 出 至 es 


Logstash 配 置 文件 


input { 


tcp { 
port => 514 
} 
} 
output{ 
elasticsearch { 
host => "127.0.0.1" 
port => "9200" 
protocol => "http" 
} 
} 
Nxlog 配 置 文件 


<Input testfile> 
Module im file 
File "C:\\test\\\*.1log" 
SavePos TRUE 

</Input> 


<Output out> 
Module om_tcp 
Host 192.168.1.100 
Port 514 

</Output> 


<Route 1> 


Path testfile => out 
</Route> 


配置 文件 修改 完毕 后 ， 重 局 服务 即 可 : 


nxlog 
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Heka 


heka Mozilla 公司 仿造 logstash 设计 ， 用 Golang 重 写 的 一 个 开源 项 目 。 同 样 采 
用 了 input -> decoder -> filter -> encoder -> output 的 流程 概念 。 其 特点 在 于 ， 在 中 
间 的 decoder/filter/encoder 部 分 ， 设 计 了 sandbox PLA > TARA AR lua 脚本 
做 这 一 部 分 的 工作 ， 降 低 了 全 程 使 用 静态 Golang 编写 的 难度 。 此 外 ， 其 filter 阶段 
还 提供 了 一 些 监控 和 统计 报警 功能 。 


官网 地 址 见 : http://nekad.readthedocs.org/ 


Mozilla 员工 已 经 在 2016 年 中 宣布 放弃 对 heka 项 目的 维护 ， 但 是 社区 依然 坚持 推 
动 了 部 分 代码 更 新 和 新 版 发 布 。 所 以 本 书 继续 保留 heka 的 使 用 介绍 。 


下 面 是 同样 的 处 理 逻 辑 ， 通 过 syslog 接收 nginx 访问 日 志 ， 解 析 并 存储 进 
Elasticsearch * heka 配置 文件 如 下 : 


[hekad] 
maxprocs = 48 


[TcpInput ] 

address = ":514" 

parser_type = "token" 

decoder = "shipped-nginx-decoder" 


[ shipped-nginx-decoder | 

type = "MultiDecoder" 

subs = ['RsyslogDecoder', 'nginx-access-decoder' ] 
cascade_strategy = "all" 

log_sub_errors = true 


[RsyslogDecoder ] 
type = "SandboxDecoder" 
filename = "lua decoders/rsyslog.lua" 
[RsyslogDecoder.config] 
type - "nginx.access" 
template = '<%pri%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg::: 
sp-if-no-1st-sp%%msg:::drop-last-1f%\n' 
tz = "Asia/Shanghai" 


[nginx-access-decoder ] 
type = "SandboxDecoder" 
filename = "lua_decoders/nginx_access.lua" 


[nginx-access-decoder.config] 

type - "combined" 

user agent transform - true 

log format = '[$time local] $http x up calling line id "$req 
uest"""$http user agent" $staTus [$remote addr] $http x log uid' 
"Shttp referer"'$request time $body bytes sent'$http x forwarded 
proto '$http x forwarded for $request uid $http host' $http cooki 
e'$upstream response time' 


[ESLogstashVOEncoder | 

es index from timestamp - true 

fields = ["Timestamp", "Payload", "Hostname", "Fields"] 
type name = "%{Type}" 


[ElasticSearchOutput] 


message matcher - "Type -- 'nginx.access'" 
server - "http://eshost.example.com:9200" 
encoder = "ESLogstashVOEncoder" 


flush interval - 50 
flush count - 5000 


heka 目前 仿造 的 还 是 旧版 本 的 logstash schema 设计 ， 所 有 切 分 字段 都 存储 在 
Qfields Fo 


经 测试 ， 其 处 理性 能 跟 开 启 了 多 线程 filters 的 logstash 进程 类 似 ， 都 在 每 秒 30000 


ae 


fluentd 


Fluentd 是 另 一 个 Ruby 语言 编写 的 日 志 收集 系统 。 和 Logstash 不 同 的 是 ， 
Fluentd 是 基于 MRI 实现 的 ， 并 不 是 利用 多 线程 ， 而 是 利用 事件 驱动 。 


Fluentd 的 开发 和 使 用 者 ， 大 多 集中 在 日 本 。 
配置 示例 


Fluentd 受 Scribe 影响 颇 深 ， 包 括 节 点 间 传 输 采 用 磁盘 buffer 来 保证 数据 不 丢失 等 
的 设计 ， 也 包括 配置 语法 。 下 面 是 一 段 配置 示例 : 


<source> 
type tail 
read from head true 
path /var/lib/docker/containers/*/*-json.log 
pos file /var/log/fluentd-docker.pos 
time format 96Y 96m -96d T96H : 96M : 96S 
tag docker.* 
format json 
«/source» 
# Using filter to add container IDs to each event 
«filter docker.var.lib.docker.containers.*.*.log» 
type record transformer 
«record» 
container id ${tag_parts[5]} 
</record> 
</filter> 


«match docker.var.lib.docker.containers.*.*.10g» 
type copy 
«store» 
# for debug (see /var/1log/td-agent.log) 
type stdout 
</store> 
<store> 
type elasticsearch 
logstash_format true 
host "Z(ENV['ES PORT_9200_TCP_ADDR']}" £ dynamically configu 
red to use Docker's link feature 
port 9200 
flush interval 5s 
</store> 
</match> 





注意 ， 虽 然 示 例 中 演示 的 是 tail 方式 。Fluentd 对 应 用 日 志 ， 并 不 推荐 如 此 读 取 。 
FLuentd 为 各 种 编程 语言 提供 了 客户 端 库 ， 应 用 可 以 直接 加 载 日 志 库 发 送 日 志 。 下 
面 是 一 个 PHP 应 用 的 示例 : 


<?php 

require_once DIR .'/src/Fluent/Autoloader.php'; 

use Fluent\Logger\FluentLogger ; 

Fluent\Autoloader::register(); 

$logger = new FluentLogger ("unix:///var/run/td-agent/td-agent.so 
ck"); 

$logger->post("fluentd.test.follow", array("from"=>"userA", "to" 
=>"userB")); 


Fluentd 使 用 如 下 配置 接收 即 可 : 


<source> 
type unix 
path /var/run/td-agent/td-agent .sock 
</source> 
<match fluentd.test.**> 
type forward 
send_timeout 60s 
recover_wait 10s 
heartbeat_interval 1s 
phi threshold 16 
hard timeout 60s 
«server» 
name myserveri 
host 192.168.1.3 
port 24224 
weight 60 
«/server» 
«server» 
name myserver2 
host 192.168.1.4 
port 24224 
weight 60 
</server> 
<secondary> 
type file 
path /var/log/fluent/forward- failed 
</secondary> 
</match> 


fluentd 插件 


作为 用 动态 语言 编写 的 软件 ，fluentd 也 拥有 大 量 插件 。 每 个 插件 都 以 RubyGem % 
式 独立 存在 。 事 实 上 ，logstash 在 这 方面 就 是 学 习 fluentd 的 。 安 装 方式 如 下 : 


/usr/sbin/td-agent-gem install fluent-plugin-elasticsearch fluen 
t-plugin-grok_parser 


fluent 


fluentd 插件 列表 ， 见 : http:/Awww.fluentd.org/plugins ° 
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Message::Passing 


Message::Passing 是 一 个 仿造 Logstash 54) Perl5 项 目 。 项 目 早 期 甚至 就 直接 照 
原样 也 叫 "Logstash" 的 名 字 。 

但 实际 上 ，Message::Passing 内 部 原理 设计 还 是 有 所 偏差 的 。 这 个 项 目 整 个 基于 
AnyEvent 事件 驱动 开发 框架 ( 即 著名 的 libev 库 ) 完 成 ， 也 要 求 所 有 插件 不 要 采取 阻 
塞 式 编程 。 所 以 ， 虽 然 项 目 开 发 不 太 活 跃 ， 插 件 接口 不 其 完善 ， 但 是 性 能 方面 却 非 
常 棒 。 这 也 是 我 从 多 个 Perl 日 志 处 理 框架 中 选择 介绍 这 个 的 原因 。 
Message::Passing 有 比较 全 的 input 和 output 插件 ， 这 意味 着 它 可 以 通过 多 种 协 
议 跟 logstash 混 跑 ， 不 过 filter 插件 比较 缺乏 。 对 等 于 grok 的 插件 叫 


示例 : 


Message::Passing 


use Message: :Passing::DSL; 
run_message_server message_chain { 
output stdout => ( 
class => 'STDOUT', 
); 
output elasticsearch => ( 
class => 'ElasticSearch', 
elasticsearch_servers => ['127.0.0.1:9200'], 
); 
encoder ( "encoder", 
class => 'JSON', 
output to => 'stdout', 
output to => 'es', 
); 
filter regexp => ( 
class -» 'Regexp', 
format -» ':nginxaccesslog', 
capture -» [qw( ts status remotehost url oh responsetime 
upstreamtime bytes )] 
output to => 'encoder', 
); 
filter logstash => ( 
class => 'ToLogstash', 
output_to => 'regexp', 
); 
decoder decoder => ( 
class -» 'JSON', 
output to => 'logstash', 
); 
input file => ( 
class -» 'FileTail', 
output to => 'decoder', 
); 
J; 
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源码 解析 


Logstash 和 过 a 日 志 收 集 系统 比 ， 优 势 就 在 于 其 源码 是 用 Ruby 写 的 ， 所 以 插 
件 开发 相当 容易 。 现 在 已 经 有 两 百 多 个 插件 可 供 选 择 。 但 是 ， 随 之 而 来 的 问题 就 
是 : ip m Java 写 ， 毕 竞 做 大 规模 系统 Java 有 天 生 优势 。 而 另 一 个 新 生 
代 fluentd 则 是 标准 的 Ruby 产品 ( 即 Matz's Ruby Interpreter) ° logstash 为 什么 选 
用 JRuby 来 实现 ， 似 乎 有 点 两 头 不 讨好 啊 ? 


乔丹 西 塞 曾 经 多 次 著 文 聊 过 这 个 问题 。 为 了 避 凑 字数 的 嫌 ， 这 里 罗列 他 的 gist 地 
H : 


e Time sucks 一 文 是 关于 Time 对 象 的 性 能 测试 ， 最 快 的 生成 方法 是 sprintf 
方法 ，MRI 性 能 为 82600 call/sec > JRuby1.6.7 为 131000 call/sec ;而 
JRuby1.7.0 为 215000 call/sec ° 

e Comparing egexp patterns speeds 一 文 是 关于 正则 表达 式 的 性 能 测试 ， 使 用 
的 正则 统一 为 (?-mix:(' (2: PA\\']4] (2:\\.)4+)*')) ， 结 有 果 MRI1.9.2 为 
530000 matches/sec ;而 JRuby1.6.5 为 690000 matches/sec ° 

e Logstash performance under ruby— x: € F logstash 本 身 数 据 流 转 性 能 的 测 
试 ， 使 用 inputs/generator 插件 生成 数据 ，outputs/staout 到 pv 工具 记 点 统 
Tt ° 285% MRI1.9.3 A 4000 events/sec， 而 JRuby1.7.0 为 25000 
events/sec ° 





可 能 你 已 经 运行 着 logstash 并 发 现 自己 的 线 上 数据 远 超过 这 个 测试 一 这 是 因为 乔 
丹 西 塞 在 2013 年 之 前 ， 一 直 是 业余 时 间 开 发 logstash， 而 且 从 未 用 在 自己 线 上 过 。 
所 以 当时 的 很 多 测试 是 在 他 自己 电脑 上 完成 的 。 


在 logstash 得 到 大 家 强烈 关注 后 ， 作 者 发 表 了 《logstash needs full time love) ， 
RY TR RHR mE 己 全 职 开发 logstash 的 工作 ， 同 时 列 出 了 1.1.0 版 本 
以 后 的 roadmap。 (不 mE m um 些 需 求 其 实 不 紧急 ， 因 为 大 
多 数 ， 或 者 说 除了 kibana 以 外 ， 至 今 依然 没有 ==!) 


时 间 轴 继续 向 前 推 ， 到 2011 年 ， 你 会 发 现 logstash 原先 其 实 也 是 用 MRI1.8.7 5 
&j ! 在 grok 模块 愉 C 扩展 改写 成 FFI 扩展 后 ， 才 正式 改 用 JRuby e 


切换 语言 的 当时 ， 乔 丹 西 塞 发 表 了 《logstash, why jruby?》 大 家 可 以 一 读 。 


事实 上 ， 时 至 今日 ， 多 种 Ruby 实现 的 痕迹 (到 处 都 有 RUBY. ENGINE 变量 判断 ) 依 
然 遍布 logstash 代码 各 处 ， 作 者 也 力图 保证 尽 可 能 多 的 代码 能 在 MRI 上 运行 。 


作为 简单 的 提示 ， 在 和 插件 无 关 的 核心 代码 中 ， 只 有 LogStash::Event 里 生成 
@timestamp 字段 时 用 了 Java 的 joda È% JRuby 仅 有 的 。 稍 微 修改 成 Ruby B 
带 的 Time 库 ， 即 可 在 MRI 上 运行 起 来 。 而 主要 插件 中 ， 也 只 有 filters/date 和 
outputs/elasticsearch 是 Java 相关 的 。 
另 一 个 温 志 预警 ，Logstash 被 Elastic.co 收购 以 后 ， 又 有 另 一 种 讨论 中 的 发 展 方 
向 ， 就 是 把 logstash 的 core 部 分 代码 ， 尽 量 的 JVM 通用 化 ， 未 来 ， 可 以 用 
JRuby，Jython、Scala，Groovy，Clojure 和 Java 等 任意 JVM 平台 语言 写 
Logstash 插件 。 


这 就 是 开源 软件 的 多 样 性 未 来 ， 让 我 们 拭目以待 吧 ~ 


pipeline 


在 一 开始 ， 就 介绍 过 ，Logstash 对 日 志 的 处 理 ， 从 input 到 output > w#1R Linux 
命令 行 上 的 管道 操作 一 样 。 事 实 上 ， 在 Logstash 中 ， 对 此 有 一 个 专门 的 名 词 ， 叫 
Pipeline。 


Pipeline 的 代码 加 载 路 径 如 下 : 


bin/logstash -> logstash-core/lib/logstash/runner.rb -> 


logstash-core/lib/logstash/agent.rb -> logstash- 
core/lib/logstash/pipeline.rb 


Logstash 从 2.2 版 开始 对 pipeline 做 了 大 幅 重 构 ， 目 前 最 新 5.0 版 的 
pipeline.rb ， 可 以 归纳 成 下 面 这 么 一 段 缩 略 版 的 代码 : 


# 初始 化 阶段 

@config = grammar.parse(configstr) 
code = @config.compile 

eval(code) 


queue = LogStash: :Util::WrappedSynchronousQueue.new 
@input_queue_client = queue.write_client 
@filter_queue_client = queue.read_client 


# 启动 指标 计数 器 
Qfilter queue client.set events metric() 
Qfilter queue client.set pipeline metric() 


# 运行 
LogStash: :Util.set_thread_name("[#{pipeline_id}]-pipeline-ma 
nager") 


# 启动 输入 插件 
@inputs.each do |input| 
input.register 
@input_threads << Thread.new do 
LogStash: :Util::set_thread_name("[#{pipeline_id}]<#{ 
input.class.config_name}") 


plugin.run(Qinput queue) 
end 
end 


Qoutputs.each {|o| o.register } 
Qfilters.each {|f| f.register } 


max inflight = batch size * pipeline workers 
pipeline workers.times do |t| 
Qworker threads «« Thread.new do 
LogStash::Util.set thread name("[Z(pipeline id)]»wor 
ker#{t}") 
@filter_queue_client.set_batch_dimensions(batch_size 
, batch_delay) 
while true 
batch = @filter_queue_client.take_batch 


# 开始 过 滤 
batch.each do |event| 
filter func(event).each do |e| 
batch.merge(e) 
end 
end 
# 计数 
@filter_queue_client.add_filtered_metrics(batch) 


# 开始 输出 
output events map = Hash.new { |h,k| h[k] = [] 


batch.each do |event| 

output func(event).each do |output | 
output events map[output].push(event) 

end 

end 

output events map.each do |output, events| 
output.multi receive(events) 

end 

Qfilter queue client.add output metrics(batch) 


H 释放 


@filter_queue_client.close_batch(batch) 
end 
end 
end 


# 运行 
@input_threads.each(&: join) 


整个 缩 略 版 ， 可 以 了 解 到 一 个 关键 信息 ， 对 我 们 理解 Logstash 原理 是 最 有 用 

的 : queue 是 一 个 固定 大 小 为 0 的 多 线程 同步 队列 。filter 和 output 插件 ， 则 在 
相同 的 pipeline_worker 线程 中 运行 ， 该 线程 每 次 批量 获取 数据 ， 也 批量 传递 
给 filter 和 output 插件 。 


由 于 input 到 filter 之 间 有 唯一 的 队列 ， 任 意 一 个 filter 或 者 output 发 生 堵塞 ， 都 会 
一 直 堵 塞 到 最 前 端的 接收 。 这 也 是 logstash-input-heartbeat 的 理论 基础 。 


这 个 全 新 的 NG pipeline 是 从 2.2 版 开始 发 布 的 ， 当 时 也 导致 logstash-output- 
elasticsearch 的 ESClient 数量 比 过 去 大 幅 增 加 ， 对 写 入 Elasticsearch 的 性 能 是 不 
利 的 。 随 后 官方 意识 到 这 个 问题 ， 并 大 举重 构 了 logstash-output-elasticsearch 的 
实现 ， 改 成 了 一 个 整体 连接 池 的 方式 ， 代 码 见 : https://github.com/logstash- 
plugins/logstash-output- 
elasticsearch/commit/06a47535111881b2bc6c9dbd3908e664e4852476 ° 4a KAY 
新 配置 参数 ， 在 之 前 插件 介绍 中 已 经 讲 过 。 


Logstash 中 Event 的 生成 


上 一 节 大 家 可 能 注意 到 了 ， 整 个 pipeline 非常 简单 ， 无 非 就 是 一 个 多 线程 的 线程 间 
数据 读 写 。 但 是 ， 之 前 介绍 的 codec 在 哪里 ? 这 个 问题 ， 并 不 在 pipeline 中 完成 ， 
而 是 plugin 中 。 


Logstash 从 1.5 开始 ， 把 各 个 plugin 拆 分 成 了 单独 的 gem， 主 代码 里 只 留 下 了 几 
个 base.rb 类 。 所 以 ， 要 了 解 详细 情况 ， 我 们 需要 阅读 一 个 实际 跑 数据 的 插件 ， 
比如  vendor/bundle/jruby/1.9/gems/logstash-input-stdin- 
3.2.0/lib/logstash/inputs/stdin.rb ° 


可 以 看 到 其 中 最 关键 的 读 取 数 据 部 分 代码 如 下 : 


@host = Socket.gethostname 
while !stop? 
if data = stdin_read 
@codec.decode(data) do |event| 
decorate(event ) 
event.set("host", @host) if !event.include?("host") 
queue << event 
end 
end 


这 里 两 个 关键 函数 : @codec.decode(line) 和 decorate(event) ° 


@codec 在 stdin.rb PRUA line > BARN RRA 
vendor/bundle/jruby/1.9/gems/logstash-codec-line- 
3.0.2/lib/logstash/codecs/line.rb 的 相关 部 分 : 


def register 
require "logstash/util/buftok" 
@buffer = FileWatch: :BufferedTokenizer .new(@delimiter ) 
@converter = LogStash: :Util::Charset.new(@charset ) 
@converter.logger = @logger 
end 
public 
def decode(data) 
Qbuffer.extract(data).each do |line| 
yield LogStash::Event.new("message" -» Qconverter.convert( 
line)) 
end 
end # def decode 


起 简短 。 就 是 在 这 个 Qcodec.decode(data) 里 ， 生 成 了 LogStash::Event 对 
和 象 。 那 么 ， 我 们 通过 output ( codec => rubydebug } 看 到 的 除了 message 
字段 以 外 的 那些 数据 ， 又 是 怎么 来 的 呢 ? 尤其 是 那个 @timestamp 是 怎么 出 来 

的 ? 


在 5.0 之 前 ， 我 们 可 以 通过 lib/logstash/event.rb 看 到 相关 属性 的 定义 和 操 
作 。5.0 之 后 ，Logstash 为 了 提高 性 能 ， 对 Event 部 分 采用 Java 语言 进行 了 重 
构 ， 现 在 你 在 ”logstash-core-event-java/lib/logstash/event.rb 里 只 能 看 
到 通过 JRuby 的 专属 require 指令 加 载 jar $938 6] T » 


想 要 了 解 Logstash::Event 的 实际 定义 ， 需 要 去 Git 仓库 下 载 ， 然 后 阅读 Java RK 
码 ， 你 也 可 以 直接 通过 网 页 阅读 ， 地 址 

是 : https://github.com/elastic/logstash/blob/master/logstash-core-event- 
java/src/main/java/org/logstash/Event.java : 


public static final String METADATA = "@metadata"; 
public static final String METADATA BRACKETS = "[" + METADATA 
+ pd gr 


public static final String TIMESTAMP = "@timestamp"; 


public static final String TIMESTAMP FAILURE TAG = " timestamp 
parsefailure"; 

public static final String TIMESTAMP FAILURE FIELD = " Qtimest 
amp"; 


public static final String VERSION = "@version"; 
public static final String VERSION_ONE = "1"; 


public Event() 

{ 
this.metadata = new HashMap<String, Object>(); 
this.data = new HashMap<String, Object>(); 
this.data.put(VERSION, VERSION_ONE); 
this.cancelled = false; 
this.timestamp = new Timestamp(); 
this.data.put(TIMESTAMP, this.timestamp); 
this.accessors = new Accessors(this.data); 
this.metadata_accessors = new Accessors(this.metadata) ; 


现在 就 清楚 了 ， 这 个 特殊 的 Qtimestamp 是 在 event 对 象 初 始 化 的 时 候 加 上 的 ， 
其 实现 同样 在 这 个 Java 源码 中 ， 见 
https://github.com/elastic/logstash/blob/master/logstash-core-event- 
java/src/main/java/org/logstash/Timestamp.java : 


public class Timestamp implements Cloneable { 
private DateTime time; 
public Timestamp() { 
this.time = new DateTime(DateTimeZone.UTC); 


这 就 是 我 们 看 到 Logstash 生成 的 事件 总 是 UTC 时 区 时 间 的 原因 。 


至 于 如 果 一 开始 就 传 入 了 @timestamp 数据 的 处 理 ， 则 是 这 样 : 


public Timestamp(String iso8601) { 
this.time = ISODateTimeFormat.dateTimeParser().parseDateTime 
(iso8601).toDateTime(DateTimeZone.UTC); 
} 
public Timestamp(long epoch_milliseconds) { 
this.time = new DateTime(epoch_milliseconds, DateTimeZone.UT 
C); 
} 


同样 会 利用 joda 库 做 一 次 解析 ， 还 是 转换 成 UTC 时 区 。 


目 己 写 一 个 插件 


前 面 已 经 提 过 在 运行 logstash 的 时 候 ， 可 以 通过 --pluginpath 参数 来 加 载 自己 
写 的 插件 。 那 么 ， 插 件 又 该 怎么 写 呢 ? 


插件 格式 
一 个 标准 的 logstash 输入 插件 格式 如 下 : 


require 'logstash/namespace' 
require 'logstash/inputs/base' 
class LogStash::Inputs::MyPlugin < LogStash::Inputs: :Base 
config name 'myplugin' 
default :codec, "line" 
config :myoption key, :validate -» :string, :default -» 'myopt 
ion value' 
public def register 
end 
public def run(queue) 
end 
end 


其 中 大 多 数 语句 在 过 滤器 和 输出 阶段 是 共有 的 。 


e config name 用 来 定义 该 插件 写 在 logstash 配置 文件 里 的 名 字 ; 

e config 可 以 定义 很 多 个 ， 即 该 插件 在 logstash 配置 文件 中 的 可 配置 参数 。 
logstash 很 温馨 的 提供 了 验证 方法 ， 确 保 接 收 的 数据 是 你 期 望 的 数据 类 型 ; 

e register logstash 在 启动 的 时 候 运 行 的 函数 ， 一 些 需 要 常 驻 内 存 的 数据 ， 可 以 
在 这 一 步 先 完成 。 比 如 对 象 初始 化 ，fijters/ruby 插件 中 的 init 语句 等 。 


插件 的 关键 方法 


输入 插件 独 有 的 是 run 方法 。 在 run 方法 中 ， 必 须 实现 一 个 长 期 运行 的 程序 (最 简单 
的 就 是 loop 指令 )。 然 后 在 每 次 收 到 数据 并 处 理 成 event ， 这 段 示例 在 上 一 节 演 
示 Logstash::Event 的 生成 时 已 经 介绍 过 。 最 后 ， 一 定 要 调用 queue << event 


语句 。 一 个 输入 流程 就 算是 完成 了 。 


而 如 果 是 过 滤器 插件 ， 对 应 修改 成 : 


require 'logstash/filters/base' 
class LogStash::Filters::MyPlugin « LogStash::Filters::Base 
config name 'myplugin' 
public def register 
end 
public def filter(event) 


filter matched(event) 
end 
end 


其 中 ， filter matched <# filter HRA X A d A CL 83 A 3E 3E 18 Z8 — x EE 
用 的 。 


输出 插件 则 是 : 


require 'logstash/outputs/base' 
class LogStash::Outputs::MyPlugin < LogStash::Outputs: :Base 
config_name 'myplugin' 
concurrency :single 
public def register 
end 
public def multi_receive(events) 
end 
end 


这 里 和 过 去 的 版 本 最 明显 的 差别 是 ， 处 理 方 法 改 成 了 multi receive ， 而 不 是 

receive 。 因 为 新 的 pipeline 机 制 是 批量 传递 数据 给 输出 插件 的 。 不 过 为 了 兼容 
过 去 的 插件 ， LogStash::Outputs::Base 基 类 中 的 multi_receive 实现 继续 
和 迭代 调用 了 receive 。 


另 一 个 是 新 出 现 的 配置 concurrency ， 代 表 着 本 插件 是 否 threadsafe， 并 由 此 取 
代 了 过 去 的 Workers 选项 。 可 选项 为 : single 和 shared 。 


e single 表示 本 插件 是 非 线程 安全 的 ， 必 须 在 各 pipeline workers 之 问 同一 时 刻 


只 有 一 个 运行 。 
e shared 表示 本 插件 是 线程 安全 的 ， 每 个 pipeline workers 之 间 可 以 独立 运行 ， 
这 也 就 意味 着 插件 作者 要 自己 在 multi receive 里 调用 Mutexes 。 


推荐 阅读 


e Extending logstash 
e Plugin Milestones 


插件 打包 


Logstash 从 1.5.0-GA 版 开始 ， 对 插件 规范 做 了 重大 变更 。 放 弃 了 milestone X 
义 ， 去 除了 --pluginpath 命令 行 参 数 。 统 一 改 成 bin/plugin 管理 的 
rubygem 包 插 件 。 那 么 ， 我 们 自己 写 的 Logstash 插件 ， 也 同样 需要 适应 这 个 新 规 
则 ， 和 写 完 Ruby 代码 ， 还 要 打包 成 gem 才能 使 用 。 


为 了 我 们 更 方便 的 完成 工作 ，logstash 针对 4 种 插件 形态 提供 了 4 个 示例 库 ， 可 以 
按照 自己 所 需 克 隆 使 用 。 比 如 要 写 一 个 logstash-filter-mything 插件 : 


git clone https://github.com/logstash-plugins/logstash- filter -ex 
ample 

cd logstash-filter-example 

mv logstash-filter-example.gemspec logstash-filter-mything.gemsp 
ec 

mv lib/logstash/filters/example.rb lib/logstash/filters/mything. 
rb 

mv spec/filters/example spec.rb spec/filters/mything spec.rb 


Rie ded E lib/logstash/filters/mything.rb 里 即 可 。 
代码 部 分 完成 。 然 后 就 是 定义 gem 打包 需要 的 额外 文件 和 库 依赖 了 。 
目录 中 有 两 个 文件 ， Gemfile 和 logstash-filter-mything.gemspec ° 


Gemfile 文件 就 是 标准 格式 ， 用 来 运行 bundler install 时 下 载 rubygems 
包 的 。 默 认 情 况 下 ， 最 基础 的 内 容 是 : 


source 'https://rubygems.org' # 国内 建议 改 成 'http://ruby.taobao.o 
rg' 

gemspec 

gem "logstash", :github -» "elastic/logstash", :branch -» "1.5" 


gemspec 文件 则 是 用 来 定义 软件 包 本 身 规范 ， 不 单 限 于 rubygems。 示 例如 下 : 


Gem: :Specification.new do |s| 


s.name = 'logstash-filter-mything' 

s.version = '1.1.0' 

s.licenses = ['Apache License (2.0)'] 

s.summary = "This mything filter is just for Elastic Stack Gui 


de example" 

s.description = "This gem is a logstash plugin required to be 
installed on top of the Logstash core pipeline using $LS_HOME/bi 
n/logstash-plugin install gemname. This gem is not a stand-alone 


program" 
s.authors = ["Chenryn"] 
.email = 'chenlin7@staff.sina.com.cn' 


S 
s.homepage = "http://kibana.logstash.es" 
s.require_paths = ["lib"] 


o 


.files = "find . -type f ! -wholename '*.svn*'^.split($*) 
s.test files = s.files.grep(%r{4(test|spec|features)/}) 


s.metadata - ( "logstash plugin" -» "true", "logstash group" - 
> "filter" } 


s.requirements << "jar 'org.elasticsearch:elasticsearch', '1.4 
SOK 

s.add_runtime_dependency "jar-dependencies" 

s.add runtime dependency "logstash-core", '>= 1.4.0', '« 2.0.0 


s.add development dependency 'logstash-devutils' 
end 


其 中 : 


g 


s.version 3L milestone % 4: 4X æ > 0.1.x 相当 于 是 milestone 0 ; 0.9.x 78 
当 于 是 milestone 2 ; 1.x.x #4 4 T milestone 3 ° 

s.file 默认 写法 是 git ls-files ， 因 为 默认 是 git 库 ， 如 果 你 本 身 采 用 
了 svn» XH cvs 库 ， 都 不 要 紧 ， 只 要 命令 列 出 的 是 你 需要 打包 进去 的 文件 即 
可 o 

s.metadata 是 logstash 的 plugin 命令 在 install 的 时 候 会 提前 verify 的 特殊 
信息 ， 一 定 要 保留 。 

s.add runtime dependency 是 定义 插件 依赖 库 的 指令 。 如 果 有 jar 包 依 


赖 ， 则 额外 再 加 s.requirements 。 


了 ， 全 部 完毕 。 下 面 打包 : 


em build logstash-filter-mything.gemspec 


了 完 就 会 生成 一 个 logstash-filter-mything-1.1.0.gem 软件 包 ， 可 以 安装 使 用 了 。 


读 取 二 进 制 文件 (utmp) 


本 节 作 者 : NERO 


我 们 知道 Linux 系 统 有 些 日 志 不 是 以 可 读 文本 形式 存在 文件 中 ， 而 是 以 二 进 制 内 容 存 
放 的 。 比 如 utmp 等 。 


Files 插 件 在 读 取 二 进 制 文件 和 文本 文件 的 区 别 在 于 没 办 法 一 行 行 处 理 内 容 ， 内 容 也 
不 是 直观 可 见 的 。 但 是 在 其 他 处 理 逻 辑 是 保持 一 致 的 ， 比 如 多 文件 支持 、 断 点 续 
传 、 内 容 监控 等 等 ， 区 别 在 于 bytes 的 截断 和 bytes 的 转换 。 在 Files 的 基础 上 ， 新 增 
了 个 插件 utmp， 插 件 实现 了 对 二 进 制 文件 的 读 取 和 解析 ， 实 现 类 似 于 文本 文件 一 行 
行 输出 内 容 ， 以 供 Filter 做 进一步 分 析 。 


utmp 新 增 了 两 个 配置 项 : struct size 和 struct format 。 


struct size 代表 结构 体 的 大 小 ，number 类 型 ; struct. format 为 结构 体 的 
内 存 分 布 格式 ，string 类 型 。 


配置 实例 


input { 
utmp { 
path => "/var/run/utmp" 
type => "syslog" 
start_position => "beginning" 
struct_size => 384 
struct format => "s21a32a4a32a256s21i1214a20" 


我 们 可 以 通过 man utmp 了 解 utmp 的 结构 体 声明 。 通 过 结构 体 声 明 我 们 能 知道 
结构 体 的 内 存 分 布 情况 。 我 们 看 struct format => 
"S2Ta32a4a32a256s2il214a20" 中 的 第 一 个 s，s 代表 short， 后 面 的 数字 2 代 
Š short 元 素 的 个 数 ， 那 么 意思 就 是 结构 体 的 第 一 个 和 第 二 个 元 素 是 short 类 型 ， 
各 占 2 个 字 节 。 


VAL RE » s21a32a4a32a256s2il214a20 总 共 代 表 384 + FH > 5 struct size 
Be a. R44 — BK » s21a32a4a322a256s2il214a20 本 质 上 是 对 应 于 Ruby 中 的 unpack 
函数 的 参数 。 其 中 s、T、a、i 等 等 含义 参见 Ruby 的 unpack 函数 说 明 。 


需要 注意 的 是 ， 你 必须 了 解 当前 操作 系统 的 字 节 序 是 大 端 模式 还 是 小 端 模式 ， 对 于 
数字 类 型 的 结构 体 元 素 很 有 必要 ， 比 如 对 于 1 和 1 的 选择 。 还 有 一 个 就 是 ， 结 构 体 
内 存 对 齐 的 问题 。 实 际 上 utmp 结构 体 第 一 个 元 素 2 字 节 ， 第 二 个 元 素 是 4 字 节 。 
编译 器 在 编译 的 时 候 会 在 第 一 个 2 字 节 后 插入 2 字 节 来 补 齐 4 字 节 ， 知 道 这 点 尤为 
重要 ， 所 以 其 实 第 二 个 short 是 无 意义 的 ， 只 是 为 了 内 存 对 其 才 有 和 补 的 。 


输出 


经 过 utmp 插件 的 event * message 字段 形 如 "field1|field2|field3" > A "|" 分 隔 每 个 
结构 体 元 素 。 可 用 Filter 插 件 进一步 去 做 解析 。utmp 本 身 只 负责 将 二 级 制 内 容 转换 
成 可 读 的 文本 ， 不 对 文件 编码 格式 负责 。 


p ox 
AC 
插件 地 址 : https://github.com/txyafx/logstash-input-utmp 


git clone https://github.com/txyafx/logstash- input -utmp 
cd logstash-input -utmp 

rm -rf .git 

vim Gemfile 修改 插件 绝对 路 径 

git init 

git add . 

gem clean 

gem build logstash-input-utmp.gemspec 


用 logstash 安 装 本 地 utmp 插 件 


Beats 平台 


Beats 平台 是 Elastic.co  packetbeat 发 展 出 来 的 数据 收集 器 系统 。beat 收集 器 可 
以 直接 写 入 Elasticsearch， 也 可 以 传输 给 Logstash。 其 中 抽象 出 来 的 libbeat， 提 
供 了 统一 的 数据 发 送 方法 ， 输 入 配置 解析 ， 日 志 记 录 框 架 等 功能 。 


也 就 是 说 ， 所 有 的 beat 工具 ， 在 配置 上 ， 除 了 input 以 外 ， 在 output ` filter ` 
shipper ` logging ` run-options 上 的 ba 都 是 完全 一 致 的 。 


filter 


5.0 版 本 后 ，beats 新 增 了 简单 的 filter 功能 ， 用 来 完成 事件 过 滤 和 字段 删 减 : 


filters: 
- drop_event: 
regexp: 
message: "ADBG:" 
- drop_fields: 
contains: 
source: "test" 
fields: ["message"] 
- include fields: 
fields: ["http.code", "http.host"] 


equals: 
http.code: 200 
range: 
gte: 
cpu.user p: 0.5 
lit: 
cpu.user_p: 0.8 
可 用 的 条 件 判 断 包括 
e equals 
e contains 


e regexp 


e range 
e or 

e and 
e not 


output 


目前 beat 可 以 发 送 数 据 给 Elasticsearch ` Logstash ` File œ Kafka ` Redis 和 
Console 六 种 目的 地 址 。 


Elasticsearch 


beats 发 送 


到 Elasticsearch 也 是 走 HTTP 接口 。 示 例 配 置 段 如 下 : 


output: 
elasticsearch: 
hosts: ["http://localhost:9200", "https://onesslip:9200/ 
path", "anotherip"] 


parameters: (pipeline: my pipeline id) 
4 仅 用 于 Elasticsearch 5.0 以 后 的 ingest 方式 

username: "user" 

password: "pwd" 

index: "topbeat" 

bulk_max_size: 20000 

flush interval: 5 

tls: 
certificate authorities: ["/etc/pki/root/ca.pem"] 
certificate: "/etc/pki/client/cert.pem" 
certificatekey: "/etc/pki/client/cert.key" 


e hosts 中 可 以 通过 URL 的 不 同形 式 ， 来 表示 HTTP 还 是 HTTPS » LEAK 
加 代理 层 的 URL 路 径 等 情况 。 
e index 表示 写 入 Elasticsearch 时 索引 的 前 级 ， 比 如 示例 即 表 示 索 引 名 为 
topbeat -yyyy.MM.dd 


Logstash 


beat € ^. Logstash 时 ， 会 配合 Logstash-1.5 后 新 增 的 metadata 特性 。 将 beat 名 
和 type 名 记录 在 metadata 里 。 所 以 对 应 的 Logstash 配置 应 该 是 这 样 : 


input { 
beats { 
port => 5044 
} 
} 
output { 
elasticsearch { 
hosts => ["http://localhost:9200"] 
index => "%{[@metadata][beat ]}-%{+YYYY.MM.dd}" 
document_type => "%{[@metadata][type]}" 
} 
} 


beat 示例 配置 段 如 下 : 


output: 
logstash: 
hosts: ["localhost:5044", "localhost:5045"] 
worker: 2 


loadbalance: true 
index: topbeat 


这 里 worker 的 含义 ， 是 beat 连 到 每 个 host 的 线程 数 。 在 loadbalance 开局 
的 情况 下 ， 意 味 着 有 4 个 worker 轮训 发 送 数据 。 


File 


output: 
file: 
path: "/tmp/topbeat" 
filename: topbeat 
rotate_every_kb: 1000 
number_of_files: 7 


Kafka 


output: 
kafka: 


hosts: ["kafka1:9092", "kafka2:9092", "kafka3:9092"] 


topic: '%{[type]}' 
topics: 
- key: “into list” 
when: 
contains: 
message: "INFO" 
- key: "debug_list" 
when: 
contains: 
message: "DEBUG" 


- key: "%{[type]}" 


mapping: 
"http": "frontend list" 
"nginx": "frontend list" 


"mysql": "backend list" 
partition: 
round robin: 
reachable only: true 
required acks: 1 
compression: gzip 
max message bytes: 1000000 


e KT max message bytes 长 度 的 事件 (注意 不 只 是 原 日 志 长 度 ) 会 被 直接 丢 


È o 


e partition 策略 默认 为 hash。 可 选项 还 有 random 和 round robin 。 
e compression 可 选项 还 有 none 和 snappy ° 


e required acks 可 选项 有 -1、0 和 1。 分 别 代表 : 等 待 全 部 副本 完成 


等 待 本 地 完成 。 


e topics 用 来 配置 基于 匹配 规则 的 选择 器 ， 支 持 When 和 mapping > when 条 


下 可 以 使 用 上 小 节 列 出 的 各 种 filter。 如 果 都 匹配 不 上 ， 则 采用 topic 配置 


Redis 


es 


output: 
redis: 
hosts: ["localhost"] 
password: "my password" 
key: "filebeat" 
db: 0 
timeout: 5 


Redis 输出 也 有 keys 配置 。 方 式 和 Kafka 的 topics 类 似 。 
Console 


output: 
console: 
pretty: true 


shipper 
shipper 部 分 是 一 些 和 网 络 拓扑 相关 的 配置 ， 就 目前 来 说 ， 大 多 数 是 packetbeat 独 
有 的 。 


shipper: 
name: "my-shipper" 
tags: ["my-service", "hardware", "test" ] 
ignore_outgoing: true 
refresh topology freq: 10 
topology expire: 15 
geoip: 
paths: 
- "/usr/share/GeoIP/GeoLiteCity.dat" 


logging 


logging: 

level: warning 

to_files: true 

to_syslog: false 

files: 
path: /var/log/mybeat 
name: mybeat.log 
keepfiles: 7 


run options 


runoptions: 
uid=501 
gid=501 


filebeat 


filebeat 


filebeat 是 基于 原先 logstash-forwarder 55 75.58 736 h RAY » MeV i& C : filebeat 就 
是 新 版 的 logstash-forwarder > 4, 4 X Elastic Stack 在 shipper 端的 第 一 选择 。 


Uu oe . JN 
Prospector 1: Spooler 
Der esfde | Estes 


QE 
ER 9 
Harvester 一 一 


Logstash 


Harvester 


Prospector 2: Kafka 
/var/log/apache2/* 
y ; 
Harvester 


error.log Redis 





Filebeat 


安装 部 团 
e deb: 


curl -L -0 https://download.elastic.co/beats/filebeat/filebe 
at 5.0.0 amd64.deb 
sudo dpkg -i filebeat 5.0.0 amd64.deb 


e rpm: 
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curl -L -0 https://download.elastic.co/beats/filebeat/filebe 
at-5.0.0-x86 64.rpm 
sudo rpm -vi filebeat-5.0.0-x86 64.rpm 


e mac: 


curl -L -0 https://download.elastic.co/beats/filebeat/filebe 
at-5.0.0-darwin.tgz 
tar xzvf filebeat-5.0.0-darwin.tgz 


e Win: 
e FT https://download.elastic.co/beats/filebeat/filebeat-5.0.0-windows.zip 


e 解压 到 C:\Program Files 

e $472 filebeat-5.0.0-windows 目录 为 Filebeat 

e 右键 点 击 PowerSHell 图 标 ， 选 择 『 以 管理 员 身 份 运行 4 
e 运行 下 列 命令 ， 将 Filebeat 安装 成 windows 服务 : 


PS > cd ‘C:\Program Files\Filebeat ' 
PS C:\Program Files\Filebeat> .Ninstall-service-filebeat.psi 


可 能 需要 额外 授予 执行 权限 。 命 令 为 : PowerShell.exe -ExecutionPolicy 


RemoteSigned -File .\install-service-filebeat.ps1 . 


filebeat 配置 


eee 
8 filebeat 在 input 段 的 配置 ， 如 下 : 


filebeat: 

spool size: 1024 # 最 大 可 
VAs 1024 条 数据 一 起 发 送出 去 

idle_timeout: "5s" # 否则 每 


E bb 72 £ eH yh 
b AP ET AULA AIR OD 


一 ^N 


registry file: ".filebeat" # 文件 读 


filebeat 


取 位 置 记录 文件 ， 会 放 在 当前 工作 目录 下 。 所 以 如 果 你 换 一 个 工作 目录 执行 filebeat 
会 导致 重复 传输 | 


config dir: "path/to/configs/contains/many/yaml" # 如 果 配 
置 过 长 ， 可 以 通过 目录 加 载 方式 拆 分 配置 
prospectors: # 有 相同 


配置 参数 的 可 以 归 类 为 一 个 prospector 


fields: 
ownfield: "mac" # 类 似 lo 
gstash 的 add_fields 
paths: 
- /var/log/system.log # 指明 读 
取 文 件 的 位 置 
- /var/log/wifi.log 
include lines: ["^ERR", "AWARN"] # 只 发 送 
包含 这 些 字 样 的 日 志 
exclude lines: ["^OK"] # 不 发 送 


包含 这 些 字样 的 日 志 


document_type: "apache" BOXE 
A ES 时 的 type 44 
ignore older: "24h" # 超过 24 


小 时 没 更 新 内 容 的 文件 不 再 监听 。 在 windows 上 另外 有 一 个 配置 叫 force close 
_ files， 只 要 文件 名 一 变化 立刻 关闭 文件 勿 柄 ， 保 证 文件 可 以 被 删除 ， 缺 陷 是 可 能 会 有 


日 志 还 没 读 完 


scan_frequency: "10s" # 4 10 
秒 钟 扫描 一 次 目录 ， 更 新 通配符 匹配 上 的 文件 列表 

tail_files: false # 是 否 从 
文件 末尾 开始 读 取 

harvester_buffer_size: 16384 # 实际 读 
取 文 件 时 ， 每 次 读 取 16384 字 节 

backoff: "1s" ju dedo 
信 测 一 次 文件 是 否 有 新 的 一 行内 容 需要 读 取 

paths : 

- "/var/log/apache/*" # 可 以 使 


用 通配符 
exclude files: ["/var/log/apache/error.log" ] 


input_type: "stdin" No fd 
og" * 2&4 "stdin" 
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multiline: 


pattern: '^[[:space:]]' 
negate: false 
match: after 

output: 


«| 


= Jo] 





我 们 已 完成 了 配置 ， 当 sudo service filebeat start 之 后 ， 你 就 可 以 在 


kibana 上 看 到 你 的 日 志 了 


字段 


Filebeat 发 送 的 日 志 包含 以 下 字段 : 


x44 


e beat.hostname beat 运行 的 主机 名 


e beat.name shipper 配置 段 设置 的 name ， 如 果 没 设 


beat .hostname 
e @timestamp 读 取 到 该 行内 容 的 时 间 
e type 通过 document_type 设 定 的 内 容 
e input type *4 "log" 还 是 "stdin" 
e source 具体 的 文件 名 全 路 径 
e offset 该 行 日 志 的 起 始 偏 移 量 
e message 日 志 内 容 
e fields 添加 的 其 他 固定 字段 都 存在 这 个 对 象 里面 


packetbeat 


目前 packetbeat 支持 的 网 络 协议 有 : HTTP » MySQL > PostgreSQL > Redis > 
Thrift >» DNS > MongoDB > Memcache ° 


对 于 很 多 Elastic Stack 新 手 来 说 ， 面 对 的 很 可 能 就 是 几 种 常用 数据 流 ， 而 书写 
logstash 正则 是 一 个 耗 时 耗 力 的 重复 劳动 ， 文 件 落地 本 身 又 是 多 余 操作 ， 
packetbeat 的 运行 方式 ， 无 疑 是 对 新 手 入 门 极 大 的 帮助 。 


安装 部 团 


packetbeat 同样 有 已 经 编译 完成 的 软件 包 可 以 直接 安装 使 用 。 需 要 注意 的 是 ， 
packetbeat 支持 不 同 的 抓 包 方式 ， 也 就 有 不 同 的 依赖 。 比 如 最 通用 的 pcap， 就 要 
求 安 装 有 libpcap 包 ，pf ring 就 要 求 有 pfring 包 ， 而 在 windows 平台 上 ， 
则 需要 下 载 安装 WinPcap 软件 。 


# yum install libpcap 

# rpm -ivh http://www.nmon.net/packages/rpm6/x86 64/PF RING/pfri 
ng-6.1.1-83.x86 64.rpm 

# rpm -ivh https://download.elasticsearch.org/beats/packetbeat/p 
acketbeat-5.0.0-x86 64.rpm 


packetbeat 还 附带 了 一 个 定制 的 Elasticsearch 模板 ， 要 在 正式 使 用 前 导入 ES 
中 o 


# curl -XPUT 'http://localhost:9200/_template/packetbeat' -d@/et 
c/packetbeat/packetbeat.template.json 


配置 示例 


过 RPM 安装 的 packetbeat 配置 文件 位 于 
/etc/packetbeat/packetbeat.yml 。 其 示例 如 下 : 


interfaces: 


device: any 
type: af_packet 


snaplen: 65536 # 保证 大 过 MTU FP 
可 ， 所 以 公 网 抓 包 的 话 可 以 改 成 1514 
buffer_size_mb: 30 # 该 参数 仅 在 af p 


acket 时 有 效 ， 表 示 在 linux 内 核 空 间 和 用 户 空间 之 间 开 启 多 大 共享 内 存 ， 可 以 减 
低 CPU 消耗 

with_vlans: false H 在 生成 抓 包 语句 的 
时 候 ， 是 否 带 上 vlan 标示 。 示 例 : "port 80 or port 3306 or (vlan and ( 
port 80 or port 3306))" 


protocols: 
dns: 
ports: [53] 
send_request: false # 通用 配置 : 是 否 将 
原始 的 request 字段 内 容 都 发 给 ES 
send_response: false A 通用 配置 : 是 否 将 
原始 的 response 字段 内 容 都 发 给 ES 
transaction_timeout: "10s" # 通用 配置 : 超过 
10 秒 的 不 再 等 待 响应 ， 直 接 认定 为 一 个 事务 ， 发 送 给 ES 
include_additionals: false # DNS 专属 配置 : 
是 否 带 上 dns.additionals 字段 
include_authorities: false # DNS 专属 配置 : 
是 否 带 上 dns.authority 字段 
http: 
ports: [80, 8080] # 抓 包 的 监听 端口 
hide keywords: ["password", "passwd" ] # 对 GET 方法 的 请 


求 参 数 ，POST 方法 的 顶层 参数 里 的 指定 关键 信息 脱 敏 。 注 意 : 如 果 你 又 开启 了 send 
request > request 字段 里 的 并 不 会 脱 敏 " 


redact_authorization: true 4 对 header 中 的 
Authorization 和 Proxy-Authorization 内 容 做 模糊 处 理 。 道 理 和 上 一 条 类 似 

send_headers: ["User-Agent"] # A headers 
对 象 里 记录 指定 的 header 字段 内 容 

send_all_headers: true # 在 headers 对 
象 里 记录 所 有 header 字段 内 容 

include body for: ["text/html"] # 在 开启 send re 
sponse 的 前 提 下 ， 只 记录 某 些 类 别 的 响应 体内 容 

split_cookie: true # 将 headers 对 
象 里 的 Cookie 或 Set-Cookie 字段 内 容 再 继续 做 KV 123] 

real ip header: "X-Forwarded-For" # 将 headers 对 


象 里 的 指定 字段 内 容 设 为 client location 和 real ip 字段 


memcache: 
ports: [11211] 
parseunknown: false 
maxvalues: 0 
maxbytespervalue: 100 
udptransactiontimeout: 10000 
mysql: 
ports: [3306] 
max_rows: 10 4 发 送 给 ES 的 S 
QL 内 容 最 多 为 10 íf 
max_row_length: 1024 4 发 送 给 ES 的 S 
QL 内 容 每 行 最 长 为 1024 TY 
cassandra: 
send_request_header: true # 在 开启 了 send. 
request 的 前 提 下 ， 记 录 cassandra request.request headers 字段 
send_response_header: true 
compressor: "snappy" 


ignored_ops: ["SUPPORTED", "OPTIONS" ] # 不 记录 部 分 操作 
amdp : 

ports: [5672] 

max_body_length: 1000 H 起 长 的 都 截断 掉 

parse_headers: true 

parse_arguments: false 

hide_connection_information: true # 不 记录 打开 、 关 闭 


连接 之 类 的 信息 
thrift: 
transport_type: socket # Thrift 传输 类 
型 ，"socket" X "framed" 
protocol_type: binary 


idl_files: ["shared.thrift"] # 一 般 来 说 默认 内 置 
的 IDL 文件 已 经 足够 了 

string_max_size: 200 # 参数 或 返回 值 中 字 
符 串 的 最 大 长 度 ， 超 长 的 都 截断 掉 

collection_max_size: 15 # Thrift 的 lis 
t, map, set, structure 结构 中 的 元 素 个 数 上 限 ， 超 过 的 元 素 丢 弃 

capture_reply: true H 为 了 节省 资源 ， 可 
以 设置 false， 只 解析 响应 中 的 方法 名 称 ， 其 余 信息 丢弃 

obfuscate_strings: true # 把 所 有 方法 参数 、 


返回 码 、 异 常 结构 中 的 字符 串 都 用 * 代替 
drop_after_n_struct_fields: 500 # 在 packetbeat 


结束 整个 事务 之 前 ， 一 个 结构 体 最 多 能 存 多 少 个 字段 。 该 配置 主要 考虑 节约 内 存 


monogodb: 
max_docs: 10 # 设置 send resp 
onse #42 F > response 字段 最 多 保存 多 少 个 文档 。 超 长 的 都 截断 掉 。 不 限 则 设 为 0 
max_doc_length: 5000 # response 字段 
里 每 个 文档 的 最 大 字 节 数 。 超 长 截断 。 不 限 则 设 为 0 
procs: 


enabled: true 
monitored: 
- process: mysqld 
cmdline_grep: mysqld 


- process: app # 设置 发 送 给 ES 
的 数据 中 进程 名 字段 的 内 容 
cmdline_grep: gunicorn # 从 /proc/<pid 


>/cmdline 中 过 滤 实际 进程 名 的 字符 串 


output: 


在 windows 上 ， 网 卡 设备 名 称 会 比较 长 。 所 以 packetbeat 单独 提供 了 一 个 参 
packetbeat -device ， 返 回 整个 可 用 网 卡 设备 列表 数组 ， 你 可 以 直接 写 数 


组 下 标 来 代表 这 个 设备 。 比 如 : device: 0 ° 


e @timestamp 事件 时 间 

e type 事件 类 型 ， 比 如 HTTP, MySQL, Redis, RUM 等 

e count 事件 代表 的 实际 事务 数 。 也 就 是 采样 率 的 倒数 

e direction 事务 流向 。 比 如 "in" 或 者 "out" 

e status 事务 状态 。 不 同 协议 取 值 方式 可 能 不 一 致 

e method 事务 方法 。 对 HTTP Æ GET/POST/PUT 等 ， 对 SQL € 
SELECT/UPDATE/INSERT 等 

e resource 事务 关联 的 逻辑 资源 。 对 HTTP 是 URL 路 径 的 第 一 个 层级 ， 对 
SQL 是 表 名 

e path 事务 关联 的 路 径 。 对 HTTP 是 URL 路 径 ， 对 SQL 是 表 名 ， 对 KVĚ 
储 是 key 

e query 人 类 可 读 的 请 求 字 符 串 。 对 HTTP X GET /resource/path? 


key=value > *% SQL Æ SELECT id FROM table WHERE name=test 

e params 请 求 参数 。 对 HTTP 就 是 GET 或 者 POST 的 请 求 参数 ， 对 Thrift 是 
request 里 的 参数 

e notes packetbeat 解析 数据 出 错时 的 日 志 记 录 


其 余 根 据 采 用 协议 不 同 ， 各 自 有 自己 的 字段 。 


dashboard 效果 


针对 packetbeat 自动 识别 的 不 同 协议 ，packetbeat 还 自 带 了 几 个 预定 义 好 的 
Kibana dashboard 方便 使 用 和 查看 。 包 括 : 


e Packetbeat Statistics: 针对 HTTP 和 标准 流量 事件 的 性 能 统计 仪表 意 
e Packetbeat Search: 用 来 搜索 关键 字 的 仪表 盘 
e MySQL Performance: MySQL 性 能 分 析 仪 表盘 
e PgSQL Performance: PgSQL 性 能 分 析 仪 表意 


预定 义 仪 表盘 的 导入 方式 如 下 : 
# git clone https://github.com/elastic/packetbeat-dashboards 


# cd packetbeat-dashboards 
# ./load.sh http://192.168.0.2:9200 


packetbeat 网 络 流量 分 析 


效果 如 下 : 
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Kibana3 topology 


其 实在 加 入 Elastic.co 2 Àf > packetbeat 曾经 自己 fork 了 一 个 Kibana3 $9 > € * 
并 在 此 基础 上 二 次 开发 了 一 个 专门 用 来 展示 网 络 拓扑 结构 的 面板 ， 叫 force panel | 
该 特性 至 今 依然 只 能 运行 在 Kibana3 上 。 所 以 ， 需 要 网 络 拓扑 展现 的 用 户 ， 还 得 继 
续 使 用 Kibana3。 部 署 方式 如 下 : 


curl -L -0 https://github.com/packetbeat/kibana/releases/downloa 
d/v3.1.2-pb/kibana-3.1.2-packetbeat.tar.gz 
tar xzvf kibana-3.1.2-packetbeat.tar.gz 


curl -L -0 https://download.elasticsearch.org/beats/packetbeat/p 
acketbeat-dashboards-k3-1.0.0-Beta1.tar.gz 

tar xzvf packetbeat-dashboards-k3-1.0.0-Betai.tar.gz 

cd packetbeat-dashboards-k3-1.0.0-Beta1/ 

./load.sh 192.169.0.2 


force panel 示例 如 下 图 。 注 意 ，force panel 用 到 的 数据 ， 其 实质 是 对 各 来 源 IP 分 
别 请 求 目 的 IP， 对 ES 的 计算 量 要 求 较 大 ， 并 不 适合 在 高 流量 高 负载 的 条 件 下 使 
用 。 


小 贴 士 


pfring 抓 包 模 式 的 原 厂 ，ntop 公司 ， 也 有 类 似 packetbeat 的 计划 。ntopng/nProbe 
除了 储存 到 SQLite 以 外 ， 也 开始 支持 存储 到 Elasticsearch 中 。 不 过 它们 推荐 采用 
的 dashboard > Æ Kibana3 的 另 一 个 fork T € > "| Qbana ° 
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有 兴趣 的 读者 可 以 参考 ntop 官方 文档 : http:/www.ntop.org/ntopng/exploring-your- 
traffic-using-ntopng-with-elasticsearchkibana/ 
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metricbeat 


使 用 beat 监控 服务 性 能 指标 是 ElasticStack 一 个 常见 的 使 用 场景 。2.x 时 代 要 求 用 
户 对 每 类 常见 都 需要 单独 开发 自己 的 xxxbeat 工具 ， 然 后 各 自 编译 使 用 。 于 是 
Elastic.co 公司 最 终 干脆 把 这 件 事情 统一 成 了 metricbeat。 


目前 metricbeat 支持 以 下 服务 性 能 指标 : 


e Apache 

e HAProxy 

e MongoDB 
e MySQL 

e Nginx 

e PostgreSQL 
e Redis 

e System 

e Zookeeper 


配置 示例 


metricbeat.modules: 

- module: system 
metricsets: 

- cpu 

- filesystem 

- memory 

- network 

- process 
enabled: true 
period: 10s 
processes: ['.*'] 
cpu ticks: false 
module: apache 
metricsets: ["status"] 
enabled: true 


period: is 
hosts ulti Al OO 


Apache 


Apache 模块 支持 2.2.31 以 上 的 2.2 系列 ， 或 2.4.16 以 上 的 2.4 系列 版 本 。 


使 用 该 模块 要 求 被 监控 的 Apache 服务 器 上 安装 配置 有 mod_status 扩展 。 通 过 
该 扩展 可 以 监控 到 的 status 数据 示例 如 下 : 


"apache": { 
statusi- 
"bytes_per_request": 1024, 
"bytes per sec": 0.201113, 
Connections 2 { 
Wasyne' = i 
rclosing = 9 
"keep alive": 0, 
"wrong c0 
ty 
"rotab 0 
ty 
repun ST 


metricbeat 


"children system": ©, 
"children user": 0, 
"load": 0.00652482, 
"system": 1.46, 
"user": 1.53 

tr 

"hostname": "apache", 

"load": { 
viur eosin 
"15": 0.31, 
tb A eal 

tr 

"requests per sec": 0.000196399, 

"scoreboard": { 
“closing connection”: 0, 
"dns_lookup": 0, 
“gracefully finishing“: ©, 
"idle_cleanup": 0, 
"keepalive": ©, 
“Logging”: 09, 
"open slot": 325, 
"reading request": 0, 
"sending reply": 1, 
Ustal taingaup 2 0; 
"total": 400, 
"waiting for connection": 74 

tr 

"total_accesses": 9, 

"total kbytes": 9, 

"uptime": { 
"server uptime": 45825, 
"uptime": 45825 


b 

"workers": ( 
"busy e. 
“vidle”: 74 


247 


模块 携带 有 一 个 预 一 定好 的 仪表 盘 ， 效 果 如 下 : 





|. 4,952,112,640 
769,080 0 p 
aisi 89,147,669 


Total accesses 

































































HAProxy 


HAProxy 模块 支持 HAProxy 服务 器 1.6 版 本 。 


使 用 该 模块 要 求 在 HAProxy 服务 器 配置 的 global 或 default 区 域 写 有 如 下 
配置 : 


stats socket 127.0.0.1:14567 


模块 可 以 采集 两 类 信息 : info 和 stat » 


其 中 info 的 返回 数据 示例 如 下 : 


"haproxy": { 
Vamos er 

"compress bps in": 0, 
"compress bps out": 0, 
"compress bps rate limit": 0, 
"conn rate": 0, 
"conn rate limit": 0, 
"cum conns": 67, 
"cum req": 67, 


"cum ssl conns": 0, 

"curr conns": 90, 
"Curr ssl conns": 0, 
"hard max conn": 4000, 
"idle pct": 100, 

"max conn": 4000, 

"max conn rate": 5, 

"max pipes": 0, 

"max sess rate": 5, 

"max sock": 8033, 

"max ssl conns": 0, 
"max ssl rate": 0, 

"max zlib mem usage": 0, 
"mem max mb": 0, 

"nb_proc": 1, 

"pid": 53858, 

"pipes_free": 0, 

"pipes used": 0, 

"process num": 1, 

"run queue": 2, 

"sess rate": 0, 
"sess rate limit": 0, 

"ssl babckend key rate": 0, 
"ssl backend max key rate": 0, 
"ssl cache misses": 0, 

"ssl cached lookups": 0, 
"ssl frontend key rate": 0, 
"ssl frontend max key rate": 0, 
"ssl frontend session reuse pct": 0, 
"ssl rate": 0, 
"ssl_rate_limit": ©, 
tasks 7, 

"ulimit_n": 8033, 
"uptime_sec": 13700, 
"zlib_mem_usage": 0 


ty 


stat 的 返回 数据 示例 如 下 : 


"haproxy": { 


Sab we 
Hace eds 
"bck' 9, 
"bin": O, 
"bout": ©, 


"check_duration": 0, 
"check_status": "L4CON", 
"chkdown": 1, 

"chkfail": 1, 

Vo lo oe (Oy 

"ctime": ©, 

"downtime": 13700, 
"dresp": 0, 
"econ": 0, 
"eresp": 0, 
"hanafail": 0 
"hrsp_1xx": 0 
"hrsp_2xx": 0 
"hrsp_3xx": 0, 
"hrsp_4xx": 0 
"hrsp_5xx": 0 
"hrsp other": 0, 

P pisce 

"last chk": "Connection refused", 
"lastchg": 13700, 

"lastsess": -1, 

"Ibtot": 09， 

PG ed 

OE EI 

"gmax": 0, 

"qtime": 60, 

"rate": 0, 

"rate max": 0, 

"rtime": ©, 

"scur": 0, 

SC ls 

"smax": 0, 

"srv_abrt": ©, 

"status": "DOWN", 


c lcu 


"svname": "log1", 
"ttime": O0, 
"weight": 1, 


"wredis": 0, 
"wretr": 0 


对 这 些 stat 数据 名 称 有 疑惑 的 ， 可 以 查阅 
http://www.haproxy.org/download/1.6/doc/management.txt 文档 ° 


MongoDB 
该 模块 支持 MongoDB 2.8 及 以 上 版 本 。 


"mongodb": ( 
"status": { 

"asserts": { 
"msg": 0, 
"regular": 0, 
"rollovers": 0, 
“user: 9; 
"warning": 0 

tr 

"background_flushing": { 
"average": { 


"ms": 16 
ty 
"flushes": 37, 
"last": f 
"ms": 18 
ty 
"last finished": "2016-09-06T07:32:58.228Z", 
.total c 
"ms": 624 
} 


ty 


"connections": { 
"available": 838859, 
"current": 1, 

"total created": 10 
ty 

"extra info": { 

"heap usage": ( 
"bytes": 62895448 

ty 

"page faults": 71 

ty 

"Journaling": { 
"commits": 1, 
"commits in write lock": 0, 
"compression": 0, 
"early commits": 0, 
"journaled": ( 


"mb": O 
1 
"times": { 

"commits": { 
"ms": O 

ie 

"commits in write lock": 
"ms": O 

15 

ro eu c 1 
"ms": O 

i 

"prep log buffer": ( 
"ms": O 

br 

"remap private view": ( 
"ms": O 

Po 

"write to data files": { 
"ms": O 

he 


"write to journal": { 
"ms": 0 


ty 
"write to data files": { 
"mb": 0 


ty 
"local time": "2016-09-06T07:33:15.546Z", 


"memory": { 


"bits": 64, 

"mapped": { 
"mb": 80 

3 

"mapped with journal": { 
"mb": 160 

ty 

"resident": { 
"mb": 57 

3 

"virtual": { 
"mb": 356 

} 

3 
"network": { 

en : 1 
"bytes": 2258 

ty 

out 4 
"bytes": 93486 

ty 


"requests": 39 

tr 

"opcounters": { 
"command": 40, 
"delete": 0, 
"getmore": 0, 
"insert": 0, 
"query": 1, 
"update": 0 

tr 


"opcounters replicated": { 


"command": 0, 
"delete": 0, 
"getmore": 0, 
"insert": 0, 


"query": 60, 
"update": 0 
ty 
"storage_engine": { 
"name": "mmapvi" 
3 
"uptime": { 
"ms": 45828938 
ty 
"version": "3.0.12", 


"write backs queued": false 


MySQL 


该 模块 支持 MySQL 5.7.0 及 以 上 版 本 。 


"mysql": ( 
"status": ( 
"aborted": { 
Ve Lienies eis 
"connects": 16 
tr 
"binlog": { 
"cache": ( 
"disk_use": 0, 
"use": 0 
} 
tr 
"bytes": { 
"received": 2100, 
"sent": 92281 
tr 


"connections": 33, 
"created": { 


"tmp": { 
"disk_tables": 
"files": 6, 
"tables": 0 

b 

tr 
"delayed": { 

"errors": 0, 

"insert threads": 

"writes": 0 

ty 


"flush commands": 1, 


"max used connections": 


"open": ( 
"files": 14, 
"streams": 0, 
"tables": 106 


ty 
"opened tables": 113 


0, 


2, 


Nginx 
该 模块 支持 Nginx 1.9 及 以 上 版 本 。 并 要 求 安 装 有 mod_stub_status 模块 。 


"nginx": ( 
"stubstatus": { 
"accepts": 227 
"active": 1, 
"current": 10, 


"dropped": 0, 
"handled": 22, 
"hostname": "nginx", 


"reading": 0, 
"requests": 10, 
"waiting": 0, 
"writing": 1 


PostgreSQL 


该 模块 支持 PostgreSQL 9 及 以 上 版 本 。 可 以 采集 activity > bgwriter 和 database 
三 类 数据 。 


activity 示例 数据 如 下 : 


"postgresql": { 


"activity": { 


ty 


"application_name": "", 
"backend start": "2016-09-06T07:33:18.323Z", 
"client": { 

"address": "172.17.0.14", 

"hostname": "", 

"port": 57436 
ty 
"database": { 

"name": "postgres", 

"oid": 12379 
3 
"pid": 162, 
"query": "SELECT * FROM pg_stat_activity", 
"query start": "2016-09-06T07:33:18.325Z", 
"state": "active", 
"state change": "2016-09-06T07:33:18.325Z', 
"transaction start": "2016-09-06T07:33:18.325Z", 
"user": { 

Dd T8. 

"name": "postgres" 


ty 


"waiting": false 


bgwriter 示例 数据 如 下 : 


"bgwriter": { 

"buffers": { 
"allocated": 191, 
"backend": 0, 
"backend_fsync": 0, 
"checkpoints": 0, 
"clean": 60, 
"Clean full": 0 

ty 

"checkpoints": { 
"requested": 0, 
"scheduled": 7, 


"times": { 
dice Mea: ce 
Pill SO 
tr 
"write": ( 
"ms": 0 
} 
} 


ty 
"stats reset": "2016-09-05T18:49:53.575Z" 


ty 


database 示例 数据 如 下 : 


"database": { 


"blocks": ( 
"lips. 
"read": 0, 
"time": { 

"read": { 
"ms": 0 

tr 

"write": ( 
"ms": 0 

} 

} 
tr 


"conflicts": 0, 
"deadlocks": 0, 
"name": "templatei", 
"number of backends": 0, 
ROOS a aks 
"rows": { 
"deleted": 0, 
"fetched": 0, 
"inserted": 0, 
"returned": 0, 


"updated": 0 
tr 
"temporary": ( 
EDU tes 
"files": 0 


ty 


"transactions": { 
"commit": 0, 
"rollback": © 


Redis 


该 模块 支持 Redis 3 及 以 上 版 本 。 可 以 采集 info 和 keyspace 两 类 数据 。 


info 示例 数据 如 下 : 


"redis": { 
EINO: A 

"clients": { 
"biggest_input_buf": 0, 
"blocked": 0, 
"connected": 2, 
"longest output list": 0 

ty 

"cluster": { 
"enabled": false 


ty 
CDU EN 
"used": { 
USVS 2 20533, 
"sys children": 0, 
"user": 0.39, 
"user children": 0 
} 
ty 
"memory": { 
"allocator": "jemalloc-4.0.3", 
"used": { 
"lua": 37888, 
"peak": 883992, 
"rss": 4030464, 
"value": 883032 
} 
tr 
"persistence": { 
AOR Es ot: 
"bgrewrite": ( 
"last status": "ok" 
tr 


"enabled": false, 
"rewrite": { 
"current time": { 
"sec": -1 


ty 


"in_progress": false, 
"last time": { 


"sec": -1 
tr 
"scheduled": false 
tr 
"write": ( 
"last_status": "ok" 
} 
tr 
"loading": false, 
Rd bi set 
"bgsave": { 
"current time": { 
"sec": -1 
ty 
"in progress": false, 
"last status": "ok", 
"last time": [f 
"sec": -1 
} 
tr 
"last save": { 
"changes since": 2, 
"time": 1475698251 
} 
} 
tr 
"replication": { 
"backlog": { 
"active": 0, 
"first byte offset": 0, 
"histlen": 0, 
"size": 1048576 
tr 
"connected slaves": 0, 
"master offset": 0, 
"role": "master" 
tr 


"server": { 


"arch_bits": "64", 

"build_id": "5575d747b4b3b12c", 
Pete ao ra E 
"gcc_version": "4.9.2", 

sor eas Lala ea av MO 

"git_shai": "00000000", 


Ezio 
"lru clock": 16080842, 
"mode": "standalone", 


"multiplexing api": "epoll", 

"os": "Linux 4.4.22-moby x86 64", 

"process id": 1, 

"run id": "d37e5ebfe0ae6c4972dbe9f0174a1637bb8247f6" 


"tcp_port": 6379, 
"uptime": 383, 
"version": "3.2.4" 
ty 
EESE f 
"commands_processed": 70, 
"connections": { 
"received": 17, 
"rejected": 0 
3 
"instantaneous": ( 
"input kbps": 0.07, 
"Ops. per. sec": 2, 
"output kbps": 0.07 


ty 

"keys": { 
"evicted": 0, 
"expired": 0 

ty 

"keyspace": { 
nats: OR 
"misses": 0 

tr 


"latest fork usec": 0, 
"migrate cached sockets": 0, 
"net": { 


"input": { 
"bytes": 1949 


tr 
"output": { 
"bytes": 4956554 
} 
tr 
"pubsub": { 
"channels": 0, 
"patterns": 0 
ty 
PSV MG see 
foie pl ad Sao DR 
"partial": { 
"err": 0, 
"ok": © 
} 
} 


ty 


keyspace 示例 数据 如 下 : 


"keyspace": { 
"avg_tt1": 0， 
"expires": 0, 
Eur DOE 
"keys": 1 

j 

j 
System 


System 就 是 过 去 的 TopBeat， 可 以 采集 core ` cpu ` diskio ` filesystem ^ fsstat ` 
load ` memory ` network 和 process 指标 。 这 都 是 运 维 人 员 最 就 悉 的 部 分 ， 就 不 再 
单独 贴 指 标 名 称 和 示例 了 。 


模块 自 带 有 一 个 预定 义 仪 表盘 ， 示 例如 下 : 


metricbeat 
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Zookeeper 


该 模块 支持 Zookeeper 3.4.0 及 以 上 版 本 。 


dicio beat.name: Descending - Q, 

á mar.local 
EE 

" 

«53500 osano 08500 80:00 835.00 099020 
timestamp per 30 seconds 
Top processes CPU usage 
0% 








New Add Save Open Share @ Last 30minutes. 
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a : 
100% 
java 70.04% 3.69% 0 
E 
Google Chrome H 57.93% 7296€ 0 
Google Chrome 22.11% 3.64% 0 
QuickLookSatell 20.85% 0.19% 0 20% 60% 
WindowServer 16.83% 1.08% 0 
408 
E 
2 
Disk utilization over time 
20 > dev á ow 
e 0835:00 08:40:00 08:45:00 08:50:00 08:55:00 08:00:00 08:35:00 08:4000 08:45:00 08:50:00 08:55:00 09:0000 
i /home timestamp per 30 seconds timestamp per 30 seconds 
i iret 
HELL Fllesystem overview 
É " 100% D € Max system filesystem. 
H Pom 
È ow H 
H H 
H s 
$ f 
© som E am 
* i 
DES 
3 
"x oh 
ogas00 。 0B4000 。 084500 。 08500  oBsso 090000 de mem pene SaL 
mar jocal: beat.name: Descending system.filesystem.device name: Descending 
Gtimestamp per 30 seconds ais i ki s 
CPU usage per process Memory usage per process 
jua > © Google Chrome H 
dx iem 6 Googie Chrome 
s 20% 
emis 9 java 
© Google Chrome @ slack 
@zoomus  softwareupdated 


15% 


10% 


Max system.process.memory.rss.pet 





08:35:00 084000 
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采集 的 mntr 数据 示例 如 下 : 
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"Zookeeper": { 
"mntr": { 
"approximate_data_size": 27, 
"ephemerals_count": 0, 


"latency": { 
"avg": 0, 
"max": 0, 
"min": 0 

ty 


"num alive connections": 1, 
"outstanding requests": 0, 


"packets": { 
"received": 10, 
"sent": 9 
ty 
"server_state": "standalone", 


"version": "3.4.8--1, built on 02/06/2016 03:18 GMT", 
"watch_count": 0, 
"Znode_count": 4 


docker 中 的 采集 方式 


metricbeat 的 system 数据 大 多 采集 自 /proc。 而 docker 中 ， 每 个 容器 的 实际 数据 
是 放 在 /hostfs 而 不 是 /proc 里 的 。 所 以 如 果 要 用 metricbeat 采集 容器 数据 ， 需 要 
先 挂 载 好 对 应 路 径 : 


$ sudo docker run \ 
--volume=/proc:/hostfs/proc:ro \ 
--volume=/sys/fs/cgroup:/hostfs/sys/fs/cgroup:ro \ 
--volume=/:/hostfs:ro \ 
--net=host 
my/metricbeat:latest -system.hostfs=/hostfs 


metricbeat 
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winlogbeat 


winlogbeat 通过 标准 的 windows API 获取 windows 系统 日 志 ， 常 见 的 有 
application > hardware » security 和 system 四 类 。winlogbeat 示例 配置 如 下 : 


winlogbeat.event_logs: 
- name: Application 
provider: 
- Application Error 
- Application Hang 
- Windows Error Reporting 
- EMET 
- name: Security 
level: critical, error, warning 
event_id: 4624, 4625, 4700-4800, -4735 
- name: System 
ignore_older: 168h 
- name: Microsoft-Windows-Windows Defender/Operational 
include_xml: true 


output.elasticsearch: 
hosts: 
- localhost:9200 
pipeline: "windows-pipeline-id" 


logging.to_files: true 
logging.files: 
path: C:/ProgramData/winlogbeat/Logs 
logging.level: info 


和 其 他 beat 一 样 ， 这 里 示例 的 配置 不 都 是 必 填 项 。 事 实 上 只 有 
event logs.name 是 必须 的 。 而 winlogbeat 的 输出 字段 中 ， 除 了 beats 家 族 的 
通用 内 容 外 ， 还 包括 一 下 特有 字段 : 


e activity id 
e computer name : 如 果 运 行 在 Windows 事件 转发 模式 ， 这 个 值 会 和 
beat.hostname 不 一 样 。 


event_data 
event_id 
keywords 
log_name 

level : 可 选 值 包括 Success, Information, Warning, Error, Audit Success, and 
Audit Failure. 
message 
message error 
record_number 
related_activity_id 
opcode 
provider_guid 
process_id 
source_name 
task 

thread_id 
user_data 
user.identifier 
user.name 
user.domain 
user.type 
version 

xml 


Elasticsearch 来 源 于 作者 Shay Banon 的 第 一 个 开源 项 目 Compass /& > fait 4S 
Java 库 最 初 的 目的 只 是 为 了 给 Shay 当时 正在 学 厨师 的 妻子 做 一 个 菜谱 的 搜索 引 
5€ o 2010 年 ，Elasticsearch 正式 发 布 。 至 今 已 经 成 为 GitHub 上 最 流行 的 Java 项 
目 ， 不 过 Shay 承诺 给 妻子 的 菜谱 搜索 依然 没有 面世 


2015 年 初 ，Elasticsearch 公司 召开 了 第 一 次 全 球 用 户 大 会 Elastic{ON}15。 诸 多 IT 
巨头 纷纷 赞助 ， 参 会 ， 演 讲 。 会 后 ，Elasticsearch 公司 宣布 改名 Elastic， 公 司 官 
网 也 变 成 http://elastic.co/。 这 意味 着 Elasticsearch 的 发 展 方向 ， 不 再 限于 搜索 业 
务 ， 也 就 是 说 ，Elastic Stack 等 机 器 数据 和 IT 服务 领域 成 为 官方 更 加 注意 的 方 

向 。 随 后 几 个 月 ， 专 注 监控 报警 的 Watcher 发 布 beta 版 ;社区 有 名 的 网 络 抓 包工 
F Packetbeat、 多 年 专注 于 基于 机 器 学 习 的 异常 探测 Prelert 等 ITOA 周边 产品 纷 
纷 被 Elastic 公司 收购 。 


Ae Hey MR FE 


本 书 作为 Elastic Stack 指南 ， 关 注 于 Elasticsearch 在 日 志和 数据 分 析 场 景 的 应 

用 ， 并 不 打算 对 底层 的 Lucene 原理 或 者 Java 编程 做 详细 的 介绍 ， 但 是 
Elasticsearch 层面 上 的 一 些 架 构 设 计 ， 对 我 们 做 性 能 调 优 ， 故 障 处 理 ， 上 有 具有 非常 重 
要 的 影响 。 

所 以 ， 作 为 ES 部 分 的 起 始 章节 ， 先 从 数据 流向 和 分 布 的 层面 ， 介绍 一 下 ES HL 
作 原 理 ， 以 及 相关 的 可 控 项 。 各 位 读者 可 以 跳 过 这 节 先 行 阅读 后 面 的 运 维 操作 部 
分 ， 但 作为 性 能 调 优 的 基础 知识 ， 依 然 建议 大 家 抽 时 间 返 回来 了 解 。 


segment、buffer 和 translog 对 实时 性 的 影响 


既然 介绍 数据 流向 ， 首 先 第 一 步 就 是 : 写 入 的 数据 是 如 何 变 成 Elasticsearch 里 可 
以 被 检索 和 聚合 的 索引 内 容 的 ? 
以 单 文件 的 静态 层面 看 ， 每 个 全 文 索引 都 是 一 个 词 元 的 倒 排 索引 ， 具 体 涉 及 到 全 文 


索引 的 通用 知识 ， 这 里 不 单独 介绍 ， 有 兴趣 的 读者 可 以 阅读 《Lucene in Action? + 
书籍 详细 了 解 。 


动态 更 新 的 Lucene 索引 


以 在 线 动态 服务 的 层面 看 ， 要 做 到 实时 更 新 条 件 下 数据 的 可 用 和 可 算 ， 就 需要 在 倒 
排 索引 的 基础 上 ， 再 做 一 系列 更 高 级 的 处 理 。 


其 实 总 结 一 下 Lucene 的 处 理 办 法 ， 很 简单 ， 就 是 一 句 话 : 新 收 到 的 数据 写 到 新 的 
索引 文件 里 。 
Lucene 把 每 次 生成 的 倒 排 索引 ， 叫 做 一 个 段 (segment)。 然 后 另外 使 用 一 个 


commit 文件 ， 记 录 索 引 内 所 有 的 segment。 而 生成 segment 的 数据 来 源 ， 则 是 内 
存 中 的 buffer。 也 就 是 说 ， 动 态 更 新 过 程 如 下 : 


segment、buffer 和 translog 对 实时 性 的 影响 


1. 当前 索引 有 3 个 segment 可 用 。 索 引 状态 如 图 2-1; 


Commit point 





Searchable 


图 2-1 


2. 新 接收 的 数据 进入 内 存 buffer。 索 引 状 态 如 图 2-2; 
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In-memory buffer 


图 2-2 
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segment、buffer 和 translog 对 实时 性 的 影响 


3. 内 存 buffer 刷 到 磁盘 ， 生 成 一 个 新 的 segment > commit 文件 同步 更 新 。 索 引 
状态 如 图 2-3。 


Commit point 


Searchable 


In-memory buffer 


图 2-3 


利用 磁盘 缓存 实现 的 准 实时 检索 


既然 涉及 到 磁盘 ， 那 么 一 个 不 可 避免 的 问题 就 来 了 : 磁盘 太 慢 了 | 对 我 们 要 求实 时 
性 很 高 的 服务 来 说 ， 这 种 处 理 还 不 够 。 所 以 ， 在 第 3 步 的 处 理 中 ， 还 有 一 个 中 间 状 
态 : 
1. A t buffer 生成 一 个 新 的 segment， 刷 到 文件 系统 缓存 中 ，Lucene 即 可 检索 
这 个 新 segment » RI & de A 2-4 » 


NO 


Commit point 


Searchable 


In-memory buffer 


图 2-4 
2. X4 A LRL AER HE SI SE E» commit 文件 更 新 。 达 到 图 2-3 中 的 状态 。 


这 一 步 刷 到 文件 系统 缓存 的 步骤， 在 Elasticsearch 中 ， 是 默认 设置 为 1 HAM 
的 ， 对 于 大 多 数 应 用 来 说 ， 几 乎 就 相当 于 是 实时 可 搜索 了 。Elasticsearch 也 提供 了 
单独 的 /_refresh 接口 ， 用 户 如 果 对 1 秒 间 隔 还 不 满意 的 ， 可 以 主动 调用 该 接 
口 来 保证 搜索 可 见 。 


注 : 5.0 中 还 提供 了 一 个 新 的 请 求 参数 : ?refresh-wait for ， 可 以 在 写 入 数据 
后 不 强制 刷新 但 一 直 等 到 刷新 才 返 回 。 


不 过 对 于 Elastic Stack 的 日 志 场景 来 说 ， 恰 恰 相 反 ， 我 们 并 不 需要 如 此 高 的 实时 
性 ， 而 是 需要 更 快 的 写 入 性 能 。 所 以 ， 一 般 来 说 ， 我 们 反而 会 通过 /_settings 
接口 或 者 定制 template 的 方式 ， 加 大 refresh interval 参数 : 


# curl -XPOST http://127.0.0.1:9200/logstash-2015.06.21/_setting 
s -d' 
{ "refresh_interval": "10s" } 


如 果 是 导入 历史 数据 的 场合 ， 那 甚至 可 以 先 完全 关闭 掉 : 


# curl -XPUT http://127.0.0.1:9200/logstash-2015.05.01 -d' 
{ 


"settings" : { 
"refresh interval": "-1" 


在 导入 完成 以 后 ， 修 改 回 来 或 者 手动 调用 一 次 即 可 : 


# curl -XPOST http://127.0.0.1:9200/logstash-2015.05.01/_refresh 


translog 提供 的 磁盘 同步 控制 


既然 refresh 只 是 写 到 文件 系统 缓存 ， 那 么 第 4 步 写 到 实际 磁盘 又 是 有 什么 来 控制 
的 ?3 如果 这 期 间 发 生 主 机 错误 、 硬 件 故障 等 异常 情况 ， 数 据 会 不 会 丢失 ? 


y 


里 ， 其 实 有 另 一 个 机 制 来 控制 。Elasticsearch 在 把 数据 写 入 到 内 存 buffer 的 同 
， 其 实 还 另外 记录 了 一 个 translog 日 志 。 也 就 是 说 ， 第 2 步 并 不 是 图 2-2 的 状 
> 而 是 像 图 2-5 这 样 : 


segment ` bufferfetranslog «I Sz I HE 85 37 v 
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B 2-5 


在 第 3 和 第 4% > refresh 发 生 的 时 候 ，translog 日 志文 件 依 然 保持 原样 ， 如 图 2- 
6: 
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也 就 是 说 ， 如 果 在 这 期 间 发 生 异 常 ，Elasticsearch A commit 位 置 开 始 ， 恢 复 整 
个 translog 文件 中 的 记录 ， 保 证 数据 一 致 性 。 


等 到 把 segment 刷 到 磁盘 ， 且 commit 文件 进行 更 新 的 时 候 ，translog 文件 才 
清空 。 这 一 步 ， 叫做 flush。 同 样 ，Elasticsearch 也 提供 了 / flush 接口 。 


x 


对 于 flush 操作 ，Elasticsearch 默认 设置 为 : 每 30 分 钟 主动 进行 一 次 flush， 或 者 
当 translog 文件 大 小 大 于 512MB ( 老 版 本 是 200MB) 时 ， 主 动 进行 一 次 flush。 这 两 
个 行为 ， 可 以 分 别 通过 index.translog.flush_threshold_period 和 
index.translog.flush_threshold_size 参数 修改 。 


如 果 对 这 两 种 控制 方式 都 不 满意 ，Elasticsearch 还 可 以 通过 
index.translog.flush_threshold_ops 参数 ， 控 制 每 收 到 多 少 条 数据 后 flush 


一 次 o 


translog 的 一 致 性 


索引 数据 的 一 致 性 通过 translog 保证 。 那 么 translog 文件 自己 呢 ? 


默认 情况 下 ，Elasticsearch 每 5 秒 ， 或 每 次 请 求 操作 结束 前 ， 会 强制 刷新 translog 
日 志 到 磁盘 上 i 


后 者 是 Elasticsearch 2.0 新 加 入 的 特性 。 为 了 保证 不 丢 数 据 ， 每 次 index ^ bulk ^ 
delete ` update 完成 的 时 候 ， 一 定 触发 刷新 translog 到 磁盘 上 ， 才 给 请 求 返回 200 
OK。 这 个 改变 在 提高 数据 安全 性 的 同时 当然 也 降低 了 一 点 性 能 。 


如 果 你 不 在 意 这 点 可 能 性 ， 还 是 希望 性 能 优先 ， 可 以 在 index template 里 设置 如 下 
参数 : 


"index.translog.durability": "async" 


Elasticsearch > 4 X % 4] 


大 家 可 能 注意 到 了 ， 前 面 一 段 内 容 ， 一 直 写 的 是 "Lucene 索引 "。 这 个 区 别 在 于 ， 
Elasticsearch 为 了 完成 分 布 式 系统 ， 对 一 些 名 词 概念 作 了 变动 。 索 引 成 为 了 整个 集 
群 级 别 的 命名 ， 而 在 单个 主机 上 的 Lucene 索引 ， 则 被 命名 为 分 片 (shard)。 至 于 数 


据 是 怎么 识别 到 自己 应 该 在 哪个 分 片 ， 请 阅读 稍 后 有 关 routing 的 章节 。 


segment merge 对 写 入 性 能 的 影响 


通过 上 节 内 容 ， 我 们 知道 了 数据 怎么 进入 ES 并 且 如 何 才 能 让 数据 更 快 的 被 检索 使 
用 。 其 中 用 一 句 话 概括 了 Lucene 的 设计 思路 就 是 " 开 新 文件 "。 从 另 一 个 方面 看 ， 
开 新 文件 也 会 给 服务 器 带 来 负载 压力 。 因 为 默认 每 1 秒 ， 都 会 有 一 个 新 文件 产生 ， 
每 个 文件 都 需要 有 文件 句柄 ， 内 存 ，CPU 使 用 等 各 种 资源 。 一 天 有 86400 秒 ， 设 
想 一 下 ， 每 次 请 求 要 扫描 一 人 遍 86400 个 文件 ， 这 个 响应 性 能 绝对 好 不 了 | 

为 了 解决 这 个 问题 ，ES 会 不 断 在 后 台 运 行 任 务 ， 主 动 将 这 些 零散 的 segment 做 数 
据 归 并 ， 尽 量 让 索引 内 只 保有 少量 的 ， 每 个 都 比较 大 的 ，segment 文件 。 这 个 过 程 
是 有 独立 的 线程 来 进行 的 ， 并 不 影响 新 segment 的 产生 。 归 并 过 程 中 ， 索 引 状 态 如 
图 2-7， 尚 未 完成 的 较 大 的 segment 是 被 排除 在 检索 可 见 范围 之 外 的 : 
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图 2-7 


当归 并 完成 ， 较 大 的 这 个 segment 刷 到 磁盘 后 ，commit 文件 做 出 相应 变更 ， 删 除 
之 前 几 个 小 segment， 改 成 新 的 大 segment。 等 检索 请 求 都 从 小 segment 转 到 大 
segment 上 以 后 ， 删 除 没 用 的 小 segment » RHR > 4 2| €. segment 数量 就 下 降 
了 ， 状 态 如 图 2-8 所 示 : 


Commit point 





Searchable 
图 2-8 


归并 线程 配置 


segment 归并 的 过 程 ， 需 要 先 读 取 segment， 归 并 计算 ， 再 写 一 遍 segment， 最 后 
还 要 保证 刷 到 磁盘 。 可 以 说 ， 这 是 一 个 非常 消耗 磁盘 IO 和 CPU 的 任务 。 所 以 ， 
ES 提供 了 对 归并 线程 的 限 速 机 制 ， 确 保 这 个 任务 不 会 过 分 影响 到 其 他 任务 。 


在 5.0 之前， 归并 线程 的 限 速 配置 
indices.store.throttle.max bytes per sec 是 20MB。 对 于 写 入 量 较 大 ， 

磁盘 转速 较 高 ， 甚 至 使 用 SSD 盘 的 服务 器 来 说 ， 这 个 限 速 是 明显 过 低 的 。 对 于 

Elastic Stack 应 用 ， 社 区 广泛 的 建议 是 可 以 适当 调 大 到 100MB 或 者 更 高 。 


# curl -XPUT http://127.0.0.1:9200/_cluster/settings -d' 
{ 





"persistent" : { 
"indices.store.throttle.max bytes per sec" : "100mb" 
} 
}' 
5.0 #46 ^ ES 对 此 作 了 大 幅度 ' 使 用 了 Lucene 的 


neni io auto throttle 机 制 ， 正 常情 况 下 已 经 不 再 需要 
手动 配置 indices.store.throttle.max per. sec 了 。 官 方 文档 中 都 已 
经 删除 了 相关 介绍 ， 不 过 从 源码 中 还 是 可 以 看 到 ， 这 个 和 值 目前 的 默认 设置 是 10240 
MB ? 


归并 线程 的 数目 ，ES 也 是 有 所 控制 的 。 黑 认 数 目的 计算 公式 是 : Math. min(3, 
Runtime.getRuntime().availableProcessors() / 2) 。 即 服务 器 CPU 核 数 的 
一 半 大 于 3 时 ， 启 动 3 个 归并 线程 ; 否则 启动 跟 CPU 核 数 的 一 半 相 等 的 线程 数 。 
相信 一 般 做 Elastic Stack 的 服务 器 CPU 合 数 都 会 在 6 个 以 上 。 所 以 一 般 来 说 就 是 
3 个 归并 线程 。 如 果 你 确定 自己 磁盘 性 能 跟 不 上 ， 可 以 降低 
index.merge.scheduler.max_thread_count 配置 ， 免 得 |O 情况 更 加 和 恶化。 
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归并 线程 是 按照 一 定 的 运行 策略 来 挑选 segment 进行 归并 的 。 主 要 有 以 下 几 条 : 


e index.merge.policy.floor segment 默认 2MB， 小 于 这 个 大 小 的 segment > 4L 
先 被 归并 。 

e index.merge.policy.max merge at once 默认 一 次 最 多 归并 10 个 segment 

e index.merge.policy.max merge at once explicit 默认 forcemerge 时 一 次 最 
多 归并 30 个 segment ° 

e index.merge.policy.max merged segment 默认 5 GB， 大 于 这 个 大 小 的 
segment， 不 用 参与 归并 。forcemerge 除外 。 


根据 这 段 策 其 实 我 们 也 可 以 从 另 一 个 角度 考虑 如 何 减 少 segment 归并 的 消耗 以 
: 加 大 flush 间隔 ， 尽 量 让 每 次 新 生成 的 segment 本 身 大 小 就 比 
较 大 。 


forcemerge 接口 


既然 默认 的 最 大 segment 大 小 是 5GB。 那 么 一 个 比较 庞大 的 数据 索引 ， 就 必然 会 
有 为 数 不 少 的 segment 永远 存在 ， 这 对 文件 句柄 ， 内 存 等 资源 都 是 极 大 的 浪费 。 但 
是 由 于 归并 任务 太 消 耗资 源 ， 所 以 一 般 不 太 选 择 加 大 

index.merge.policy.max merged segment 配置 ， 而 是 在 负载 较 低 的 时 间 段 ， 
通过 forcemerge 接口 ， 强 制 归并 segment ° 


# curl -XPOST http://127.0.0.1:9200/logstash-2015-06.10/_forceme 
rge?max_num_segments=1 


由 于 forcemerge 线程 对 资源 的 消耗 比 普通 的 归并 线程 大 得 多 ， 所 以 ， 绝 对 不 建议 
对 还 在 写 入 数据 的 热 索 引 执 行 这 个 操作 。 这 个 问题 对 于 Elastic Stack 来 说 非常 好 
办 ， 一 般 索 引 都 是 按 天 分 割 的 。 更 合适 的 任务 定义 方式 ， 请 阅读 本 书 稍 后 的 curator 
章节 。 


routing 和 replica 的 读 写 过 程 


之 前 两 节 ， 完 整 介绍 了 在 单个 Lucene 索引 ， 即 ES 分 片 内 的 数据 写 入 流程 。 现 在 
彻底 回 到 ES 的 分 布 式 层 面 上 来 ， 当 一 个 ES 节点 收 到 一 条 数据 的 写 入 请 求 时 ， 它 
是 如 何 确 认 这 个 数据 应 该 存储 在 哪个 节点 的 哪个 分 片上 的 ? 


路 由 计算 


作为 一 个 没有 额外 依赖 的 简单 的 分 布 式 方案 ，ES 在 这 个 问题 上 同样 选择 了 一 个 非 
常 简洁 的 处 理 方式 ， 对 任 一 条 数据 计算 其 对 应 分 片 的 方式 如 下 : 


shard = hash(routing) % number_of_primary_shards 


每 个 数据 都 有 一 个 routing 参数 ， 默 认 情 况 下 ， 就 使 用 其 id theo HH _ia fa 
计算 哈 希 后 ， 对 索引 的 主 分 片 数 取 余 ， 就 是 数据 实际 应 该 存储 到 的 分 片 ID e 


由 于 取 余 这 个 计算 ， 完 全 依赖 于 分 母 ， 所 以 导致 ES 索引 有 一 个 限制 ， 索 引 的 主 分 
片 数 ， 不 可 以 随意 修改 。 因 为 一 旦 主 分 片 数 不 一 样 ， 所 以 数据 的 存储 位 置 计算 结果 
都 会 发 生 改 变 ， 索 引 数 据 就 完全 不 可 读 了 。 


副本 一 致 性 


作为 分 布 式 系统 ， 数 据 副 本 可 算是 一 个 标 配 。ES 数据 写 入 流程 ， 自 然 也 涉及 到 副 
本 。 在 有 副本 配置 的 情况 下 ， 数 据 从 发 向 ES 节点 ， 到 接 到 ES 节点 响应 返回 ， 流 
向 如 下 ( 附 图 2-9) : 


1. 客户 端 请 求 发 送 给 Node 1 节点 ， 注 意图 中 Node 1 是 Master 节点 ， 实 际 完全 
可 以 不 是 。 

2. Node 1 用 数据 的 _id 取 余 计算 得 到 应 该 讲 数据 存储 到 shard 0 上 。 通 过 
cluster state 信息 发 现 shard 0 的 主 分 片 已 经 分 配 到 了 Node 3 上 。Node 1 转 
发 请 求 数据 给 Node 3。 

3. Node 3 完成 请 求 数 据 的 索引 过 程 ， 存 入 主 分 片 0。 然 后 并 行 转发 数据 给 分 配 有 
shard 0 的 副本 分 片 的 Node 1 fe Node 2。 当 收 到 任 一 节点 汇报 副本 分 片 数 据 
写 入 成 功 ，Node 3 即 返回 给 初始 的 接收 节点 Node 1， 宣 布 数据 写 入 成 功 。 
Node 1 返回 成 功 响应 给 客户 端 。 


NODE 1 - * MASTER NODE 2 NODE 3 


CLUSTER 





图 2-9 
这 个 过 程 中 ， 有 几 个 参数 可 以 用 来 控制 或 变更 其 行为 : 


e wait_for active shards 上 面 示例 中 ，2 个 副本 分 片 只 要 有 1 个 成 功 ， 就 可 以 
返回 给 客户 端 了 。 这 点 也 是 有 配置 项 的 。 其 默认 值 的 计算 来 源 如 下 : 


int( (primary + number_of_replicas) / 2 ) + 1 


根据 需要 ， 也 可 以 将 参数 设置 为 one， 表 示 仅 写 完 主 分 片 就 返回 ， 等 同 于 async; 
还 可 以 设置 为 all， 表示 等 所 有 副本 分 片 都 写 完 才 能 返回 。 


e timeout 如 果 集 群 出 现 异 常 ， 有 些 分 片 当 前 不 可 用 ，ES 默认 会 等 待 1 分 钟 看 分 
能 否 恢 复 。 可 以 使 用 ?timeout=30s 参数 来 缩短 这 个 等 待 时 间 。 


副本 配置 和 分 片 配 置 不 一 样 ， 是 可 以 随时 调整 的 。 有 些 较 大 的 索引 ， 甚 至 可 以 在 做 
forcemerge 前 ， 先 把 副本 全 部 取消 掉 ， 等 optimize 完 后 ， 再 重新 开局 副本 ， 节 约 
单个 segment 的 重复 归并 消耗 。 


# curl -XPUT http://127.0.0.1:9200/logstash-mweibo-2015.05.02/_s 
ettings -d '{ 
"index": { "number_of_replicas" : 0 } 


} 1 


shard 的 allocate 控制 


X shard 分 配 在 哪个 节点 上 ， 一 般 来 说 ， 是 由 ES 自动 决定 的 。 以 下 几 种 情况 会 
触发 分 配 动作 : 

1. 新 索引 生成 

2. 索引 的 删除 

3. 新 增 副 本 分 片 

4. 节点 增 减 引发 的 数据 均衡 


ES 提供 了 一 系列 参数 详细 控制 这 部 分 逻辑 : 


cluster.routing.allocation.enable 该 参数 用 来 控制 允许 分 配 哪 种 分 片 。 默 认 是 
all 。 可 选项 还 包括 primaries 和 new primaries 。 none 则 彻底 拒 
绝 分 片 。 该 参数 的 作用 ， 本 书 稍 后 集群 升级 章节 会 有 说 明 。 
cluster.routing.allocation.allow_rebalance 该 参数 用 来 控制 什么 时 候 允许 数据 
均衡 。 黑 认 是 indices all active ， 即 要 求 所 有 分 片 都 正常 启动 成 功 以 
后 ， 才 可 以 进行 数据 均衡 操作 ， 否 则 的 话 ， 在 集群 重启 阶段 ， 会 浪费 大 多 流量 
ee 
cluster.routing.allocation.cluster_concurrent_rebalance 该 参数 用 来 控制 集群 
内 同时 运行 的 数据 均衡 任务 个 数 。 默 认 是 2 个 。 如 果 有 节点 增 减 ， 且 集群 负载 
压力 不 高 的 时 候 ， 可 以 适当 加 大 。 
cluster.routing.allocation.node initial primaries recoveries 该 参数 用 来 控制 节 
点 重启 时 ， 人 允许 同 时 恢复 几 个 主 分 片 。 默 认 是 4 个 。 如 果 节 点 是 多 磁盘 ， 且 
IO 压力 不 大 ， 可 以 适当 加 大 。 
cluster.routing.allocation.node_concurrent_recoveries 该 参数 用 来 控制 节点 除 
了 主 分 片 重启 恢复 以 外 其 他 情况 下 ， 允 许 同时 运行 的 数据 恢复 任务 。 默 认 是 2 
个 。 所 以 ， 节 点 重启 时 ， 可 以 看 到 主 分 片 迅 速 恢复 完成 ， 副 本 分 片 的 恢复 却 很 
慢 。 除 了 副本 分 片 本 身 数 据 要 通过 网 络 复制 以 外 ， 并 发 线程 本 身 也 减少 了 一 
半 。 当 然 ， 这 种 设置 也 是 有 道理 的 一 一 主 分 片 一 定 是 本 地 恢复 ， 副 本 分 片 却 需 
要 走 网 络 ， 带 宽 是 有 限 的 。 从 ES 1.6 开始 ， 冷 索引 的 副本 分 片 可 以 本 地 恢 
复 ， 这 个 参数 也 就 是 可 以 适当 加 大 了 。 
indices.recovery.concurrent streams 该 参数 用 来 控制 节点 从 网 络 复制 恢复 副 
本 分 片 时 的 数据 流 个 数 。 默 认 是 3 个 。 可 以 配合 上 一 条 配置 一 起 加 大 。 
indices.recovery.max bytes per sec 该 参数 用 来 控制 节点 恢复 时 的 速率 。 黑 
认 是 40MB。 显 然 是 比较 小 的 ， 建 议 加 大 。 


此 外 ，ES 还 有 一 些 其 他 的 分 片 分 配 控制 策略 。 比 如 以 tag 和 rack id 作为 区 
分 等 。 一 般 来 说 ，Elastic Stack 场景 中 使 用 不 多 。 运 维 人 员 可 能 比较 常见 的 策略 有 
两 种 : 
1. 磁盘 限额 为 了 保护 节点 数据 安全 ，ES 会 定时 
( cluster.info.update.interval > RU 30 秒 ) 检 查 一 下 各 节点 的 数据 目录 
磁盘 使 用 情况 。 在 达到 
cluster.routing.allocation.disk.watermark.low (默认 85%) 的 时 候 ， 
新 索引 分 片 就 不 会 再 分 配 到 这 个 节点 上 了 。 在 达到 
cluster.routing.allocation.disk.watermark.high (默认 90%) 的 时 
候 ， 就 会 触发 该 节点 现存 分 片 的 数据 均衡 ， 把 数据 挪 到 其 他 节点 上 去 。 这 两 个 
值 不 但 可 以 写 百分比 ， 还 可 以 写 具体 的 字 节 数 。 有 些 公 司 可 能 出 于 成 本 考虑 ， 
对 磁盘 使 用 举 有 一 定 的 要 求 ， 需 要 适当 抬 高 这 个 配置 : 


# curl -XPUT localhost:9200/_cluster/settings -d '{ 


"transient" : { 
"cluster.routing.allocation.disk.watermark.low" : "85%", 
"cluster.routing.allocation.disk.watermark.high" : "10gb 

s 
"cluster.info.update.interval" : "1m" 


1. 热 索 引 分 片 不 均 默认 情况 下 ，ES 集群 的 数据 均衡 策略 是 以 各 节点 的 分 片 总 数 
(indices_all_active) 作 为 基准 的 。 这 对 于 搜索 服务 来 说 无 疑 是 均衡 搜索 压力 提 
高 性 能 的 好 办 法 。 但 是 对 于 Elastic Stack 场景 ， 一 般 压 力 集中 在 新 索引 的 数据 
写 入 方面 。 正 常 运行 的 时 候 ， 也 没有 问题 。 但 是 当 集 群 扩容 时 ， 新 加 入 集群 的 
节点 ， 分 片 总 数 远 远 低 于 其 他 节点 。 这 时 候 如 果 有 新 索引 创建 ，ES 的 默认 策 
略 会 导致 新 索引 的 所 有 主 分 片 几乎 全 分 配 在 这 台新 节点 上 。 整 个 集群 的 写 入 压 
力 ， 压 在 一 个 节点 上 ， 结果 很 可 能 是 这 个 节点 直接 被 压 死 ， 集 群 出 现 异 常 。 所 
以 ， 对 于 Elastic Stack 场景 ， 强 烈 建议 大 家 预先 计算 好 索引 的 分 片 数 后 ， 配 置 
好 单 节 点 分 片 的 限额 。 比 如 ， 一 个 5 节点 的 集群 ， 索 引 主 分 片 10 个 ， 副 本 1 
份 。 则 平均 下 来 每 个 节点 应 该 有 4 个 分 片 ， 那 么 就 配置 : 


# curl -s -XPUT http://127.0.0.1:9200/logstash-2015.05.08/_setti 
ngs -d '( 

"index": ( "routing.allocation.total shards per node" : "5" 
} 


注意 ， 这 里 配置 的 是 5 而 不 是 4。 因 为 我 们 需要 预防 有 机 器 故障 ， 分 片 发 生 迁 移 的 
情况 。 如 果 写 的 是 4， 那 么 分 片 迁 移 会 失败 。 


此 外 ， 另 一 种 方式 则 更 加 玄妙 ，Elasticsearch 中 有 一 系列 参数 ， 相 互 影响 ， 最 终 联 
合 决定 分 片 分 配 : 


e cluster.routing.allocation.balance.shard 节点 上 分 配 分 片 的 权重 ， 默 认为 
0.45。 数 值 越 大 越 倾 向 于 在 节点 层面 均衡 分 片 。 

e cluster.routing.allocation.balance.index 每 个 索引 往 单个 节点 上 分 配 分 片 的 权 
重 ， 默 认为 0.55。 数 值 越 大 越 倾 向 于 在 索引 层面 均衡 分 片 。 

e cluster.routing.allocation.balance.threshold 大 于 阅 值 则 触发 均衡 操作 。 默 认为 
1 o 


Elasticsearch 中 的 计算 方法 是 : 


(indexBalance (node.numShards(index) — avgShardsPerNode(index)) + 
shardBalance (node.numShards() — avgShardsPerNode)) <=> weightthreshold 


所 以 ， 也 可 以 采取 加 大 cluster.routing.allocation.balance.index > #2 
设置 cluster.routing.allocation.balance.shard 为 0 来 尽量 采用 索引 内 的 
节点 均衡 。 


reroute 接口 
上 面 说 的 各 种 配置 ， 都 是 从 策略 层面 ， 控 制 分 片 分 配 的 选择 。 在 必要 的 时 候 ， 还 可 
以 通过 ES 的 reroute 接口 ， 手 动 完成 对 分 片 的 分 配 选 择 的 控制 。 


reroute 接口 支持 五 种 指令 : allocate replica , allocate stale primary , 
allocate_empty_primary ， move 和 cancel 。 常 用 的 一 般 是 allocate 和 
move : 


e allocate * 指令 


因为 负载 过 高 等 原因 ， 有 时 候 个 别 分 片 可 能 长 期 处 于 UNASSIGNED 状态 ， 我 们 就 
可 以 手动 分 配 分 片 到 指定 节点 上 。 黑 认 情 况 下 只 允许 手动 分 配 副本 分 片 (即使 用 
allocate replica )， 所 以 如 果 要 分 配 主 分 片 ， 需 要 单独 加 一 个 

accept data loss 选项 : 


# curl -XPOST 127.0.0.1:9200/ cluster/reroute -d '( 


"commands" : [ { 
"allocate stale primary" 
{ 
"index" : "logstash-2015.05.27", "shard" : 61, "no 
de" : "10.19.0.77", "accept_data_loss" : true 
} 


] 
} 1 


注意 ，allocate_stale_primary 表示 准备 分 配 到 的 节点 上 可 能 有 老 版 本 的 历史 
数据 ， 运 行 时 请 提前 确认 一 下 是 哪个 节点 上 保留 有 这 个 分 片 的 实际 目录 ， 且 目录 大 
小 最 大 。 然 后 手动 分 配 到 这 个 节点 上 。 以 此 减少 数据 丢失 。 


e move 指令 


因为 负载 过 高 ， 磁 盘 利用 率 过 高 ， 服 务 器 下 线 ， 更 换 磁 盘 等 原因 ， 可 以 会 需要 从 节 


» 


curl -XPOST 127.0.0.1:9200/ cluster/reroute -d '( 


"commands" : [ { 
"move" 
{ 
"index" : "logstash-2015.05.22", "shard" : 0, "fro 
m node" : "10.19.0.81", "to node" : "10.19.0.104" 
} 
} 


分 配 失 败 原因 


如 果 是 自己 手工 reroute AK > Elasticsearch 返回 的 响应 中 会 带 上 失败 的 原因 。 
过 格式 非常 难看 ， 一 堆 YES，NO ° M 5.0 版 本 开始 ，Elasticsearch 新 增 了 
allocation explain 接口 ， 专 门 用 来 解释 指定 分 片 的 具体 失败 理由 : 


" curl -XGET ‘http://localhost:9200/_cluster/allocation/explain’ -d'( "index": 
"logstash-2016.10.31", "shard": 0, "primary": false 


y 


得 到 的 响应 如 下 : 


{ "shard" : { "index" : "myindex", "index uuid" : "KnW0-ZELRs6PK84l0r38ZA", "id" : 
0, "primary" : false }, "assigned" : false, "shard state fetch pending": false, 
"unassigned info" : { "reason" : "INDEX CREATED^", "at" : "2016-03- 
22120:04:23.620Z" }, "allocation delay ms" : 0, "remaining delay ms" : 0, 
"nodes" : ( "V-SpiOAyRZ6ZvKbal3691w" : ( "node name" : "H5dfFeA", 

"node attributes" : ( "bar" : "baz" }, "store" : ( "shard copy" : "NONE" }, 

"final decision" : "NO", "final explanation" : "the shard cannot be assigned 
because one or more allocation decider returns a 'NO' decision", "weight" : 
0.06666675, "decisions" : [ ( "decider" : "filter", "decision" : "NO", "explanation" : 
"node does not match index include filters [foo:\"bar\"]" } ] }, 
"QceVL8c5RWaw1qXZORg57g" : { ... 


这 会 是 很 长 一 串 JSON， 把 集群 里 所 有 的 节点 都 列 上 来 ， 挨 个 解释 为 什么 不 能 分 配 到 这 
个 节点 


1H 节 点 JP 2 


aree 节点 出 现 故障 预警 等 情况 ， 需 要 下 线 ， 也 是 Elasticsearch 运 维 工作 中 

常见 的 情况 。 如 果 已 经 稳定 运行 过 一 段 时 间 的 集群 ， po M T2822 
分 片 。 这 种 时 候 通 过 reroute 接口 手动 转移 ， 就 显得 太 过 麻烦 了 。 这 个 时 候 ， 有 另 一 
种 方式 : 


curl -XPUT 127.0.0.1:9200/ cluster/settings -d '{ "transient" :{ 
"cluster.routing.allocation.exclude. ip" : "10.0.0.1" } Y 


Elasticsearch 集群 就 会 自动 把 这 个 IP 上 的 所 有 分 片 ， 都 自动 转移 到 其 他 节点 上 
。 等 到 转移 完成 ， 这 个 空 节点 就 可 以 毫 无 影响 的 下 线 了 。 


和 ^ ip^ 类似 的 参数 还 有 ^ host `， ~_name’ 等。 此外， 这 类 参数 不 单 是 clust 
er 级 别 ， 也 可 以 是 index 级 别 。 下 一 小 节 就 是 index 级 别 的 用 例 。 


HH 冷 热 数据 的 读 写 分 网 


Elasticsearch 集群 一 个 比较 突出 的 问题 是 : 用 户 做 一 次 大 的 查询 的 时 候 ， 非常 大 
量 的 读 IO 以 及 聚合 计算 导致 机 器 Load 升 高 ，CPU 使 用 率 上 升 ， 会 影响 阻塞 到 新 
数据 的 写 入 ， 这 个 过 程 其 至 会 持续 几 分 钟 。 所 以 ， 可 能 需要 仿照 MySQL 集群 一 样 ， 做 


读 写 分 离 。 
HHH 实施 方案 


1. N 台 机 器 做 热 数 据 的 存储 ， 上 面 只 放 当 天 的 数据 。 这 台 热 数据 节点 上 面 的 ela 
sticsearc.yml 中 配置 “node.attr.tag: hot^ 

2. 之 前 的 数据 放 在 另外 的 M 人 台 机 器 上 。 这 M 人 台 冷 数据 节点 中 配置 “node.attr.t 
ag: stale' 

3. 模板 中 控制 对 新 建 索引 添加 hot 标签 : 


Wa n 


{ "order" : 0, "template" : "*", "settings" : { "index.routing.allocation.include.tag" : 
"hot" } } 


4. 每 天 计划 任务 更 新 索引 的 配置 ， 将 tag 更 改 为 stale, 索引 会 自动 迁移 到 MG 
冷 数 据 节点 


curl -XPUT 
http://127.0.0.1:9200/indexname/_ settings - 
d' 


{ "index": { "routing": { "allocation": { "include": { "tag": "stale" }}}}} " 


这 样 ， 写 操作 集中 在 N 台 热 数据 节点 上 ， 大 范围 的 读 操作 集中 在 M 台 冷 数据 节点 
上 。 避 免 了 堵塞 影响 。 


shard # allocated +] 


该 方案 运用 的 ， 是 Elasticsearch 中 的 allocation filter 功能 ， 详 细 说 明 
见 : https://www.elastic.co/guide/en/elasticsearch/reference/master/shard- 
allocation-filtering.html 
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集群 自动 发 现 


ES 是 一 个 P2P 类 型 (使 用 gossip 协议 ) 的 分 布 式 系统 ， 除 了 集群 状态 管理 以 外 ， 其 
他 所 有 的 请 求 都 可 以 发 送 到 集群 内 任意 一 台 节 点 上 ， 这 个 节点 可 以 自己 找到 需要 转 
发 给 哪些 节点 ， 并 且 直 接 跟 这 些 节 点 通信 。 


所 以 ， 从 网 络 架 构 及 服务 配置 上 来 说 ， 构 建 集群 所 需要 的 配置 极其 简单 。 在 
Elasticsearch 2.0 之 前 ， 无 阻碍 的 网 络 下 ， 所 有 配置 了 相同 cluster.name 的 节 
点 都 自动 归属 到 一 个 集群 中 。 


2.0 版 本 之 后 ， 基 于 安全 的 考虑 ，Elasticsearch 稍 作 了 调整 ， 避 免 开 发 环境 过 于 随 
便 造 成 的 麻烦 。 


unicast 方式 


ES 从 2.0 版 本 开始 ， 默 认 的 自动 发 现 方式 改 为 了 单 播 (unicast) 方 式 。 配 置 里 提供 几 
台 节 点 的 地 址 ，ES 将 其 视 作 gossip router 角色 ， 借 以 完成 集群 的 发 现 。 由 于 这 只 

是 ES 内 一 个 很 小 的 功能 ， 所 以 gossip router 角色 并 不 需要 单独 配置 ， 每 个 ES Y 
点 都 可 以 担任 。 所 以 ， 采 用 单 播 方 式 的 集群 ， 各 节点 都 配置 相同 的 几 个 节点 列表 作 

为 router 即 可 。 


此 外 ， 考 虑 到 节点 有 时 候 因为 高 负载 ， 慢 GC 等 原因 可 能 会 有 偶尔 没 及 时 响应 ping 
包 的 可 能 ， 一 般 建 议 稍微 加 大 Fault Detection 的 超时 时 间 。 


同样 基于 安全 考虑 做 的 变更 还 有 监听 的 主机 名 。 现 在 默认 只 监听 本 地 lo 网 卡 上 。 所 
以 正式 环境 上 需要 修改 配置 为 监听 具体 的 网 卡 。 


network.host: "192.168.0.2" 

discovery.zen.minimum_master_nodes: 3 

discovery.zen.ping timeout: 100s 

discovery.zen.fd.ping timeout: 100s 
discovery.zen.ping.unicast.hosts: ["10.19.0.97","10.19.0.98","10 
.19.0.99","10.19.0.100"] 


上 面 的 配置 中 ， 两 个 timeout 可 能 会 让 人 有 所 迷惑 。 这 里 的 fd Æ fault detection 的 
缩写 。 也 就 是 说 : 


e discovery.zen.ping timeout 参数 仅 在 加 入 或 者 选举 master 主 节点 的 时 候 才 起 
作用 ; 


e discovery.zen.fd.ping_timeout 参数 则 在 稳定 运行 的 集群 中 ，master 检测 所 有 


节点， 以 及 节点 检测 master 是 否 畅通 时 长 期 有 用 。 


既然 是 长 期 有 用 ， 自 然 还 有 运行 间隔 和 重 试 的 配置 ， 也 可 以 根据 实际 情况 调整 : 


discovery.zen.fd.ping interval: 10s 
discovery.zen.fd.ping retries: 10 


增删 改 查 


增删 改 查 是 数据 库 的 基础 操作 方法 。ES 虽然 不 是 数据 库 ， 但 是 很 多 场合 下 ， 都 被 

人 们 当做 一 个 文档 型 NoSQL 数据 库 在 使 用 ， 原 因 自 然 是 因为 在 接口 和 分 布 式 架构 
层面 的 相似 性 。 虽 然 在 Elastic Stack 场景 下 ， 数 据 的 写 uu dV 

Logstash 和 Kibana 代劳 ， 作 为 测试 、 调 研 和 排 错 时 的 基本 功 ， 还 是 需要 了 解 一 下 
ES 的 增删 改 查 用 法 的 。 


数据 写 入 


ES 的 一 大 特点 ， 就 是 全 RESTful 接口 处 理 JSON 请 求 。 所 以 ， 数 据 写 入 非常 简 
a: a 


# curl -XPOST http://127.0.0.1:9200/logstash-2015.06.21/testlog 
-d E 


"date" : "1434966686000", 
"user" : "chenlin7", 
"mesg" : "first message into Elasticsearch" 


} 1 
命令 返回 响应 结果 为 : 


{"_index":"logstash-2015.06.21","_type":"testlog","_id":"AU4ew3h 
2nBE6nOqcyVJK", "_version":1, "created": true} 


数据 获取 


可 以 看 到 ， 在 数据 写 入 的 时 候 ， 会 返回 该 数据 的 id 。 这 就 是 后 续 用 来 获取 数据 
的 关键 : 


# curl -XGET http://127.0.0.1:9200/logstash-2015.06.21/testlog/A 
UAew3h2nBE6nOqcyV JK 


命令 返回 响应 结果 为 : 


{"_index":"logstash-2015.06.21","_type":"testlog", "_id":"AU4ew3h 
2nBE6nOqcyVJK", "_version":1, "found": true," source": { 


"date" : "1434966686000", 
"user" : “chenlin7", 
"mesg" : "first message into Elasticsearch" 


tt 


这 个 source 里 的 内 容 ， 正 是 之 前 写 入 的 数据 。 


如 果 觉 得 这 个 返回 看 起 来 有 点 太 过 麻烦 ， 可 以 使 用 curl -XGET 
http://127.0.0.1:9200/logstash- 
2015.06.21/testlog/AU4ew3h2nBE6nOqcyVJK/_source 来 指明 只 获取 源 数 据 部 


分 。 


更 进一步 的 ， 如 果 你 只 想 看 数据 中 的 一 部 分 字段 内 容 ， 可 以 使 用 curl -XGET 
http://127.0.0.1:9200/logstash- 

2015 .06.21/testlog/AU4ew3h2nBE6nOqcyVIK?fields=user,mesg 来 指明 获取 
字段 ， 结 果 如 下 : 


(" index":"logstash-2015.06.21"," type":"testlog"," id":"AUJ4ew3h 
2nBE6nOqcyVJK"," version":1,"found":true, "fields":("user":["chen 
lin7"],"mesg":["first message into Elasticsearch"]}} 


数据 删除 
要 删除 数据 ， 修 改 发 送 的 HTTP 请 求 方法 为 DELETE 即 可 : 


# curl -XDELETE http://127.0.0.1:9200/logstash-2015.06.21/testlo 
g/AU4ew3h2nBE6n0qcyVJK 


删除 不 单 针 对 单条 数据 ， 还 可 以 删除 整个 整个 索引 。 基 至 可 以 用 通配符 。 


# curl -XDELETE http://127.0.0.1:9200/logstash-2015.06.0* 


在 Elasticsearch 2.x 之 前 ， 可 以 通过 查询 语句 删除 ， 也 可 以 删除 某 个 _type A 
的 数据 。 现 在 都 已 经 不 再 内 置 支持 ， 改 为 Delete by Query 插件 。 因 为 这 种 方 


式 本 身 对 性 能 影响 较 大 | 


数据 更 新 


已 经 写 过 的 数据 ， 同 样 还 是 可 以 修改 的 。 有 两 种 办 法 ， 一 种 是 全 量 提交 ， 即 指明 
id 再 发 送 一 次 写 入 请 求 。 


# curl -XPOST http://127.0.0.1:9200/logstash-2015.06.21/testlog/ 
AUAew3h2nBE6nOqcyVJK -d '{ 


"date" : "1434966686000", 
"user" : "chenlin7", 
"mesg" " "first message into Elasticsearch but version 2" 


D 
另 一 种 是 局 部 更 新 ， 使 用 / update 接口 : 


# curl -XPOST 'http://127.0.0.1:9200/10gstash-2015.06.21/testlog 
/AUAew3h2nBE6nOqcyVJK/ update' -d '( 
Hoes a f 


"user" : "someone" 


# curl -XPOST 'http://127.0.0.1:9200/10gstash-2015.06.21/testlog 
/AUAew3h2nBE6nOqcyVJK/ update' -d '( 


"script" : "ctx. source.user = \"someone\"" 


} 1 


搜索 请 求 


上 节 介 绍 的 ， 都 是 针对 单条 数据 的 操作 。 在 ES 环境 中 ， 更 多 的 是 搜索 和 聚合 请 
求 。 在 5.0 之 前 版 本 中 ， 数 据 获取 和 数据 搜索 甚至 有 极 大 的 区 别 : 刚 写 入 的 数据 ， 
可 以 通过 translog 立刻 获取 ; 但 是 却 要 等 到 refresh 成 为 一 个 segment 后 ， 才 能 被 
搜索 到 。 从 5.0 版 本 开始 ，Elasticsearch 稍 作 了 改动 ， 不 再 维护 doc-id 到 translog 
offset 的 映射 关系 ， 一 旦 GET 请 求 到 这 个 还 不 能 搜 到 的 数据 ， 就 强制 refresh 出 来 
segment， 这 样 就 可 以 搜索 了 。 这 个 改动 降低 了 数据 获取 的 性 能 ， 但 是 节省 了 不 少 
A> wT young GC 次 数 ， 对 写 入 性 能 的 提升 是 很 有 好 处 的 。 


本 节 介 绍 ES 的 搜索 语法 。 


全 文 搜索 


ES 对 搜索 请 求 ， 有 简易 语法 和 完整 语法 两 种 方式 。 简 易 语 法 作为 以 后 在 Kibana 上 
最 常用 的 方式 ， 一 定 是 需要 学 会 的 。 而 在 命令 行 里 ， 我 们 可 以 通过 最 简单 的 方式 来 
做 到 。 还 是 上 节 输 入 的 数据 : 


# curl -XGET http://127.0.0.1:9200/logstash-2015.06.21/testlog/ 
search?q=first 


可 以 看 到 返回 结果 : 


{"took":240, "timed_out": false," shards": {"total":27, "successful" 
:27, "failed":0},"hits":{"total":1, "max_score":0.11506981, "hits": 
[(" index":"logstash-2015.06.21"," type":"testlog"," id":"AUAew3 
h2nBE6nOqcyVJK"," score":0.11506981," source":( 


"date" : "1434966686000", 

"user" : "chenlin7", 

"mesg" : "first message into Elasticsearch" 
33133 


还 可 以 用 下 面 语句 搜索 ， 结 果 是 一 样 的 。 


# curl -XGET http://127.0.0.1:9200/logstash-2015.06.21/testlog/_ 
search?q=user:"chenlin7" 


querystring 语法 


上 例 中 ， 2q= 后 面 写 的 ， 就 是 querystring 语法 。 鉴 于 这 部 分 内 容 会 在 Kibana 上 
经 常 使 用 ， 这 里 详细 解析 一 下 语法 : 


e 全 文 检索 : 直接 写 搜索 的 单词 ， 如 上 例 中 的 first ; 

e 单字 段 的 全 文 检 索 : 在 搜索 单词 之 前 加 上 字段 名 和 冒号 ， 比 如 如 果 知 道 单词 
first 肯定 出 现在 mesg 字段 ， 可 以 写作 mesg:first ; 

单字 段 的 精确 检索 : 在 搜索 单词 前 后 加 双 引 号 ， 比 如 user:"chenlin7" ; 
多 个 检索 条 件 的 组 合 : 可 以 使 用 NOT, AND 和 OR 来 组 合 检索 ， 注 意 必 须 
是 大 写 。 比 如 user:("chenlin7" OR "chenlin") AND NOT 


mesg:first : 
段 是 否 存在 : exists :user. 表示 要 求 user 字段 存 

> missing :user 表示 要 求 user 字段 不 存在 ; 

e 通配符 :用 ? 表示 单字 母 ， * 表示 任意 个 字母 。 比 如 fir?t mess* ; 

e 正则 : 需要 比 通 配 符 更 复杂 一 点 的 表达 式 ， 可 以 使 用 正则 。 比 如 
mesg:/mes{2}ages?/ 。 注 意 ES 中 正则 性 能 很 差 ， 而 且 支 持 的 功能 也 不 是 
特别 强大 ， 尽 量 不 要 使 用 。ES 支持 的 正则 语法 
见 : https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl- 


regexp-query.html#regexp-syntax : 

近似 搜索 : 用 ~ 表示 搜索 单词 可 能 有 一 两 个 字母 写 的 不 对 ， 请 ES 按照 相似 
度 返回 结果 。 比 如 frist- ; 

范围 搜索 : 对 数值 和 时 间 ，ES 都 可 以 使 用 范围 搜索 ， 比 

如 : rtt:>300 > date:["now-6h" TO "now"} Ae Xv» [] 表示 端点 
数值 包含 在 范围 内 ， {} 表示 端点 数值 不 包含 在 范围 内 ; 


完整 语法 


ES 支持 各 种 类 型 的 检索 请 求 ， 除 了 可 以 用 querystring 语法 表达 的 以 外 ， 还 有 很 多 
其 他 类 型 ， 具 体 列表 和 示例 可 参 

JL : https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl- 
queries.html ° 


作为 最 简单 和 常用 的 示例 ， 这 里 展示 一 下 term query 的 写法 ， 相 当 于 querystring 
语法 中 的 user:"chenlin7" 


# curl -XGET http://127.0.0.1:9200/_search -d ' 
{ 
"query": { 
"term": { 
"user": "chenlin7" 


聚合 请 求 


在 检索 范围 确定 之 后 ，ES 还 支持 对 结果 集 做 聚合 查询 ， 返 回 更 直接 的 聚合 统计 结 
果 。 在 ES 1.0 版 本 之 前 ， 这 个 接口 叫 Facet，1.0 版 本 之 后 ， 这 个 接口 改 为 
Aggregation ° 


Kibana 分 别 在 v3 中 使 用 Facet > v4 中 使 用 Aggregation。 不 过 总 的 来 说 ， 
Aggregation 是 Facet 接口 的 强化 升级 版 本 ， 我 们 直接 了 解 Aggregation 即 可 。 本 
书后 续 章节 也 会 介绍 如 何在 Kibana 的 v3 版 本 中 使 用 aggregation 接口 做 二 次 开 
发 。 


HERE TH Bl 


在 Elasticsearch 1.x #3  » aggregation 分 为 bucket fe metric 两 种 ， 分 别 用 作 
词 元 划分 和 数值 计算 。 而 其 中 的 bucket aggregation， 还 支持 在 自身 结果 集 的 基础 
> #7044) aggregation。 这 就 是 aggregation +t facet 最 领先 的 地 方 。 比 如 实现 
一 个 时 序 百分比 统计 ， 在 facet 接口 就 无 法 直接 完成 ， 而 在 aggregation 接口 就 很 
简单 了 : 


# curl -XPOST 'http://127.0.0.1:9200/10gstash-2015.06.22/ search 
?size-O&pretty' -d'( 
"aggs" : { 
"percentile over time" : ( 
"date histogram" : { 
"field" : "Qtimestamp", 
"interval" : "1h" 
ty 
"aggs" : { 
"percentile_one_time" : { 
"percentiles" : { 
"field" : "requesttime" 


得 到 结果 如 下 : 


"took" : 151595, 
"timed_out" : false, 
"_ shards" : { 
Sota Seay 
"successful" : 81, 
"failed" : 0 
tr 
PLES a att 
"total" : 3307142043, 
"max_score" : 1.0, 
Hiest si] 
tr 
"aggregations" : { 
"percentile over time" : { 
"buckets" : [ { 
"key as string" : "22/Jun/2015:22:00:00 +0000", 
"key" : 1435010400000, 


"doc_count" : 459273981, 
"percentile one time" : { 
"values" : ( 
"1.0" : 0.004, 
"5.0" : 0.006, 


E2520), 0.023, 
"50.0" 0.035, 
SO 0.08774675719725569, 
"95,0" 0.25732934416125663, 
"99,0" 0. 7508899754871812 
} 
} 
jet 
"key as string" : "23/Jun/2015:00:00:00 +0000", 


"key" : 1435017600000, 
"doc count" : 768620219, 
"percentile one time" : ( 
"values" : { 
"1.0" : 0.004, 
"5.0" : 0.007000000000000001, 


12570 0.025, 
"50.0" 0.03987809503972864, 
LASS o 0.10297843567746187, 
"95.0" 0.30047269327062875, 
"99.0" 1.015495933753329 
Ji 
J 
}, i 
"key as string" : "23/Jun/2015:02:00:00 +0000", 


"key" : 1435024800000, 
"doc count" : 849467060, 
"percentile one time" : { 
"values" : { 
"1.0" : 0.004, 
"5,0" : 0.008, 


P2530 0.027000000000000003, 
"50.0" 0.0439999899006102, 
a750 0.1160416197625958, 
190501 0 . 3383140614483838, 
"99.0" 1.0275839684542212 


} 
yl 
} 
} 
} 
管道 聚合 示例 


在 Elasticsearch 2.x 中 ， 新 增 了 pipeline aggregation 类 型 。 可 以 在 已 有 
aggregation 返回 的 数组 数据 之 后 ， 再 对 这 组 数值 做 一 次 运算 。 最 常见 的 ， 就 是 对 
时 序数 据 求 移动 平均 值 。 比 如 对 响应 时 间 做 周期 为 7， 移 动 窗口 为 30，alpha, 
beta, gamma 参数 均 为 0.5 的 holt-winters 季节 性 预测 2 个 未 来 值 的 请 求 如 下 : 


"aggs" : { 
"my date histo" : { 
"date histogram" : ( 
"field" : "@timestamp", 
"interval" : "1h" 
ty 
agds a a uf 
"avgtime" : { 
"avg" : { "field" : "requesttime" } 
3 
"the movavg" : { 
"moving avg" : { 
"buckets path" : "avgtime", 
"window" : 30, 
"model" : "holt winters", 
"predict" : 2, 
"settings" : { 
"type" : "mult", 
"alpha" : 0.5, 
"beta" : 0.5, 
"gamma" : 0.5, 
"period" : 7, 
"pad" : true 
} 
} 
} 
} 
} 
} 
} 
响应 如 下 
{ 
tOOK e 12; 
"timed out" : false, 
" shards" : ( 


"total" : 10, 


"successful" : 10, 
"failed" : 0 
tr 
V bicis af 
"Eobtaldto910]59]391. 
"max score" : 0.0, 
AD gale tes ER 
tr 
"aggregations" : ( 
"my date histo" : { 
"buckets" : [ { 
"key as string" : "2015-12-24T02:00:00.000Z", 
"key" : 1450922400000, 
"doc count" : 1462, 
"avgtime" : { 
"value" : 508.25649794801643 


}, { 
} {í 
"key as string" : "2015-12-24T17:00:00.000Z", 
"key" : 1450976400000, 
"doc count" : 1664, 
"avgtime" : ( 
"value" : 504.7067307692308 


tr 
"the movavg" : { 
"value" : 500.9766851760192 
j 
} {í 
} { 
"key as string" : "2015-12-25T09:00:00.000Z", 
"key" : 1451034000000, 
"doc_count" : 0, 
"the_movavg" : { 
"value" : 493.9519632950849, 
"value as string" : "1970-01-01T00:00:00.493Z" 
} 


p 


可 以 看 到 ， 在 第 一 个 移动 窗口 还 没 满 足 之 前 ， 是 没有 移动 平均 值 的 ; 而 在 实际 数据 
已 经 结束 以 后 ， 虽 然 没 有 平均 值 了 ， 但 是 预测 的 移动 平均 值 却 还 有 数 。 
buckets_path 语法 


由 于 aggregation 是 有 堆 且 层级 关系 的 ， 所 以 pipeline aggregation 在 引用 metric 
aggregation 时 也 就 会 涉及 到 层级 的 问题 。 在 上 例 中 ， the_movavg 和 avgtime 
是 同一 层级 ， 所 以 buckets_path 直接 写 avgtime m 。 但 是 如 果 我 们 把 
the_movavg 上 提 一 层 ， 跟 my date histo 同 级 ， 这 个 buckets path 怎么 
BAH? 


"buckets path" : "my_date_histo>avgtime" 


如 果 用 的 是 返回 的 数值 有 多 个 值 的 聚合 ， 比 如 percentiles 或 者 
extended stats ， 则 是 : 


"buckets path" : "percentile_over_time>percentile_one_time.95" 


ES 目前 能 支持 的 聚合 请 求 列表 ， 参 
IL : https://www.elastic.co/guide/en/elasticsearch/reference/current/search- 
aggregations.html ° 


See Also 


Holt Winters 预测 算法 ， 见 : https://en.wikipedia.org/wiki/Holt-Winters ° X-4& 3& 2E 
领域 最 著名 的 运用 是 RRDtool 中 的 HWPREDICT ° 


search 请 求 参 数 
e from 
从 索引 的 第 几 条 数据 开始 返回 ， 默 认 是 0 ; 


e size 


返回 多 少 条 数据 ， 黑 认 是 10。 

注意 : Elasticsearch 集群 实际 是 需要 给 coordinate node 返回 shards number * 
(from + size) 条 数据 ， 然 后 在 单机 上 进行 排序 ， 最 后 给 客户 端 返回 这 个 size K 
小 的 数据 的 。 所 以 请 谨 懂 使 用 from 和 size 参数 。 

此 外 ，Elasticsearch 2.x 还 新 增 了 一 个 索引 级 别 的 动态 控制 配置 

项 : index.max result window ， 默 认为 10000。 即 from + size 大 于 
10000 的 话 ，Elasticsearch 直接 拒绝 掉 这 次 请 求 不 进行 具体 搜索 ， 以 保护 节点 。 
另外 ，Elasticsearch 2.x 还 提供 了 一 个 小 优化 : 当 设 置 "size":0 时 ， 自 动 改变 
search type 为 count。 跳 过 搜索 过 程 的 fetch 阶段 。 


e timeout 


coordinate node 等 待 超时 时 间 。 到 达 该 阅 值 后 ，coordinate node 直接 把 当前 收 到 
的 数据 返回 给 客户 端 ， 不 再 继续 等 待 data node 后 续 的 返回 了 。 

注意 : 这 个 参数 只 是 为 了 配合 客户 端 程序 ， 并 不 能 取消 掉 data node 上 搜索 任务 还 
在 继续 运行 和 占用 资源 。 


e terminate_after 
各 data node 上 ， 扫 描 单 个 分 片 时 ， 找 到 多 少 条 记录 后 ， 就 认为 足够 了 。 这 个 参数 


可 以 切实 保护 data node 上 搜索 任务 不 会 长 期 运行 和 占用 资源 。 但 是 也 就 意味 着 搜 
索 范 围 没 有 履 盖 全 部 索引 ， 是 一 个 抽样 数据 。 准 确 率 是 不 好 判断 的 。 


e request_cache 


各 data node 上 ， 在 分 片 级 别 ， 对 请 求 的 响应 ( 仅 限于 hits.total 数值 、 
aggregation 和 suggestion 的 结果 集 ) 做 的 缓存 。 注 意 : 这 个 缓存 的 键 值 要 求 很 严 
格 ， 请 求 的 ISON 必须 一 字 不 易 ， 缓 存 才能 命中 。 


另外 ， request cache 参数 不 能 写 在 请 求 JSON 里 ， 只 能 以 URL 参数 的 形式 存 
在 。 示 例如 下 : 


curl -XPOST http://localhost:9200/ search?request cache-true -d 


{ 


"size" : 0, 

"timeout" : "120s", 
"terminate_after" : 1000000, 
"query" s { “match_all"“" : 人 }, 
"aggs" : { "terms" : { "terms" 


{ "field" 


"keyname" } } } 


script 


Elasticsearch 中 ， 可 以 使 用 自 定 义 脚本 扩展 功能 。 包 括 评分 、 过 滤 函 数 和 聚合 字段 
等 方面 。 内 置 脚本 引擎 历经 MVEL、Groovy、Lucene expression 的 变换 后 ， 
Elastic.co 最 终 决 定 实现 一 个 自己 专用 的 Painless 脚本 语言 ， 并 在 5.0 版 正式 发 
^de 


作为 Elastic Stack 场景 ， 我 们 只 介绍 在 聚合 字段 方面 使 用 Script 的 方式 。 


动态 提交 


最 简单 多 用 的 方式 ， 就 是 在 正常 的 请 求 体 中 ， 把 field 换 成 script 提交 。 比 
如 一 个 标准 的 terms agg AOR script 方式 ， 写 法 如 下 : 


# curl 127.0.0.1:9200/logstash-2015.06.29/_search -d '( 
"aggs" : { 
"clientip_topi0" : { 


"terms" : { 
ESC Gel pile aces 
"lang" : "painless", 
"inline" : "doc['clientip'].value" 
} 
} 


} 1 


在 script 中 ， 有 三 种 方式 引用 数 
据 : doc['clientip'].value ^ _field['clientip'].value 和 
_source.clientip 。 其 区 别 在 于 : 


e doc[].value 读 取 doc value 内 的 数据 ; 
e field[] 读 取 field 设置 "store":true 的 存储 内 容 ; 


e _source.obj.attr 读 取 source 的 JSON 内 容 。 


这 也 意味 着 ， 前 者 必须 读 取 的 是 最 终 的 词 元 字段 数据 ， 而 后 者 可 以 返回 任意 的 数据 
结构 。 


注意 : 如 果 有 分 词 ， 且 未 禁用 fielddata 的 话 ， doc[].value 读 取 到 的 是 分 词 后 
的 数据 。 所 以 请 注意 使 用 doc['clientip.keyword'].value 写法 。 


5| x UE 
为 了 和 动态 提交 的 语法 有 区 别 ， 调 用 国定 文件 的 写法 如 下 : 


# curl 127.0.0.1:9200/logstash-2015.06.29/_search -d '( 


"aggs" : { 
"clientip subnet topi10" : { 
"terms" : { 
PSCIHDE a f 
"file" : "getvalue", 
"lang" : "groovy", 
"params" : { 
"fieldname": "clientip.keyword", 
"pattern": "A((?:\d{1,3}\.?){3})\.\d{1,3 
$$" 
} 
} 
} 
} 
} 
y! 


上 例 要 求 在 ES 集群 的 所 有 数据 节点 上 ， 都 保存 有 一 个 
/etc/elasticsearch/scripts/getvalue.groovy 文件 ， 并 且 该 脚本 文件 可 以 
接收 fieldname 和 pattern 两 个 变量 。 试 举例 如 下 


#!/usr/bin/env groovy 
matcher = ( doc[fieldname].value =~ /${pattern}/ ) 
if (matcher.matches()) { 

matcher [0][1] 


Painless H 5 


注意 : ES 进程 默认 每 分 钟 扫 描 一 次 /etc/elasticsearch/scripts/ 目录 ， 并 
尝试 加 载 该 目录 下 所 有 文件 作为 script。 所 以 ， 不 要 在 该 目录 内 做 文件 编辑 等 工 

作 ， 不 要 分 发 svn 等 目录 到 生成 环境 ， 这 些 临 时 或 者 隐藏 文件 都 会 被 ES 进程 加 载 
然后 报错 。 


其 他 语言 


Qi 


ES 支持 通过 插件 方式 ， 扩 展 脚本 语言 的 支持 ， 目 前 默认 自 带 的 语言 包括 : 


e painless 

e lucene expression 
e groovy 

e mustache 


而 github 上 目前 已 有 以 下 语言 插件 支持 ， 基 本 履 益 了 所 有 JVM 上 的 可 用 语言 : 


e https://github.com/elastic/elasticsearch-lang-mvel 
e https://github.com/elastic/elasticsearch-lang-javascript 


https://github.com/elastic/elasticsearch-lang-python 


https://github.com/hiredman/elasticsearch-lang-clojure 


https://github.com/felipehummel/elasticsearch-lang-scala 
e https://github.com/fcheung/elasticsearch-jruby 


reindex 


Elasticsearch 本 身 不 提供 对 索引 的 rename > mapping 的 alter 等 操作 。 所 以 ， 如 
果 有 需要 对 全 索引 数据 进行 导出 ， sie ees XE SEE UU 
下 ， 我 们 只 能 通过 scroll API 导出 全 部 数据 ， 然 后 重新 做 一 次 索引 写 入 。 这 个 过 
程 ， 叫 做 reindex ° 


之 前 完成 这 个 过 程 只 能 自己 写 程序 或 者 用 logstash。5.0 中 ，Elasticsearch 将 这 
过 程 内 置 为 reindex API， 但 是 要 注意 : 这 个 接口 并 没有 什么 黑 科 技 ， aa 
是 将 这 段 相同 逻辑 的 代码 预 置 分 发 而 已 。 如 果 有 复杂 的 数据 变更 操作 等 细节 需求 ， 
依然 需要 自己 编程 完成 


下 面 分 别 给 出 这 三 种 方法 的 示例 : 


Bra 
Perl & P 35 
Elastic 官 SPESE SSE pP3 > HP Perl 库 提 供 了 对 reindex 比较 方便 的 
写法 和 示例 。 通 过 cpanm Search::Elasticsearch 命令 安装 库 完毕 后 ， 使 用 以 
下 程序 即 可 : 


use Search: :Elasticsearch; 


my $es = Search: :Elasticsearch->new( 
nodes => ['192.168.0.2:9200'] 

); 

my $bulk = $es-»bulk helper( 
index => 'new index', 


): 


$bulk-»reindex( 
source => { 


index => 'old_index', 
size => 500, # default 
search_type => 'scan' # default 


Logstash 做 reindex 


在 最 新 版 的 Logstash 中 ， 对 logstash-input-elasticsearch 插件 做 了 一 定 的 修改 ， 
使 得 通过 logstash 完成 reindex 成 为 可 能 。 


reindex 操作 的 logstash 配置 如 下 : 


input { 
elasticsearch { 
hosts => [ "192.168.0.2" ] 
index => "old_index" 
size => 500 
scroll => "5m" 
docinfo => true 
} 
} 
output { 
elasticsearch { 
hosts => [ "192.168.0.3" ] 
index => "%{[@metadata][_index]}" 
document_type => "%{[@metadata][_type]}" 
document id => "%{[@metadata][_id]}" 


如 果 你 做 reindex 的 源 索 引 并 不 是 logstash 记录 的 内 容 ， 也 就 是 没有 
Qtimestamp , @version 这 两 个 logstash 字段 ， 那 么 可 以 在 上 面 配置 中 添加 一 
& filter 配置 ， 确 保 前 后 索引 字段 完全 一 致 : 


filter { 
mutate { 
remove_field => [ "@timestamp", "@version" ] 


reindex API 


简单 的 reindex， 可 以 很 容易 的 完成 : 


curl -XPOST http://localhost:9200/_reindex -d ' 


f 
"source": ( 
"index": "logstash-2016.10.29" 
ty 
"dest": { 
"index": "logstash-new-2016.10.29" 
} 
} 1 


复杂 需求 ， 也 能 通过 配合 其 他 API， 比 如 script ^ pipeline 等 来 满足 一 些 ， 下 面 举 一 
个 复杂 的 示例 : 


curl -XPOST http://localhost:9200/ reindex?requests per second-1 
0000 -d ' 


{ 
"source": { 
"remote": { 
"host": "http://192.168.0.2:9200", 
ty 
"index": "metricbeat-*", 
"query": { 
"match": { 
"host": "webserver" 
} 
} 
tr 
"dest": { 
"index": "metricbeat", 
"pipeline": "ingest-rule-1" 
tr 
SG 
"lang": "painless", 
"inline": "ctx. index = 'metricbeat-' + (ctx. index.substrin 


g('metricbeat-'.length(), ctx. index.length())) + '-1'" 
j 
} ' 


上 面 这 个 请 求 的 作用 ， 是 将 来 自 192.168.0.2 集群 的 metricbeat-2016.10.29 索引 
中 ， 有 关 host:webserver 的 数据 ， 读 取出 来 以 后 ， 经 过 localhost 集群 的 
ingest-rule-1 规则 处 理 ， 在 写 入 localhost 集群 的 metricbeat-2016.10.29-1 & 
引 中 。 


注意 : 读 取 远 端 集群 数据 需要 先 配 置 对 应 的 
reindex.remote.whitelist:192.168.0.2:9200 到 elasticsearch.yml 的 白 名 

单 里 。 

通过 reindex 接口 运行 的 任务 可 以 通过 同样 是 5.0 新 引入 的 任务 管理 接口 进行 取 

消 、 修 改 等 操作 。 详 细 介 绍 见 后 续 任务 管理 章节 。 
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批量 提交 


在 CRUD 章节 ， 我 们 已 经 知道 ES 的 数据 写 入 是 如 何 操作 的 了 。 喜 欢 自 己 动手 的 读 
者 可 能 已 经 迫不及待 的 自己 写 了 程序 开始 往 ES 里 写 数据 做 测试 。 这 时 候 大 家 会 发 
现 : 程序 的 运行 速度 非常 一 般 ， 即 使 ES 服务 运行 在 本 机 ， 一 秒 钟 大 概 也 就 能 写 入 
几 百 条 数据 。 


这 种 速度 显然 不 是 ES 的 极限 。 事 实 上 ， 每 条 数据 经 过 一 次 完整 的 HTTP POST 请 
求 和 ES indexing 是 一 种 极 大 的 性 能 浪费 ， 为 此 ，ES 设计 了 批量 提交 方式 。 在 数 
据 读 取 方 面 ， 叫 mget 接口 ， 在 数据 变更 方面 ， 叫 bulk 接口 。mget 一 般 常用 于 搜 
索 时 ES 节点 之 间 批 量 获取 中 间 结 果 集 ， 对 于 Elastic Stack 用 户 ， 更 常见 到 的 是 
bulk 接口 。 


bulk 接口 采用 一 种 比较 简朴 的 数据 积累 格式 ， 示 例如 下 : 


# curl -XPOST http://127.0.0.1:9200/_bulk -d' 

{ "create" : { " xndex" : "test", "_type" : "type1" } } 

{ "fieldi" : "valuei" } 

{ "delete" : { " index" : "test", " type" : "typei" } } 

{ "index" : { " index" : "test", " type" : "type1", Ae sso | : ust 

} 

{ "fieldi" : "value2" } 

{ "update" : : Puta Wo : uu " type" : "typei", " index" : "test") 
} 

{ "doc" : {"field2" : "value2"} } 


格式 是 ， 每 条 JSON 数据 的 上 面 ， 加 一 行 描述 性 的 元 JSON， 指 明 下 一 行 数 据 的 操 
KRA BRIEF 


采用 这 种 格式 ， 而 不 是 一 般 的 JSON 数组 格式 ， 是 因为 接收 到 bulk 请 求 的 ES 节 
点 ， 就 可 以 不 需要 做 完整 的 JSON 数组 解析 处 理 ， 直 接 按 行 处 理 简短 的 元 JSON ， 
就 可 以 确定 下 一 行 数据 JSON 转发 给 哪个 数据 节点 了 。 这 样 ， 一 个 固定 内 存 大 小 的 
network buffer 空间 ， 就 可 以 反复 使 用 ， 又 节省 了 大 量 JVM 的 GC。 


事实 上 ， 产 品级 的 logstash * rsyslog ` spark 都 是 默认 采用 bulk 接口 进行 数据 写 入 
的 。 对 于 打算 自己 写 程序 的 读者 ， 建 议 采 用 Perl 的 
Search::Elasticsearch::Bulk 或 者 Python 的 elasticsearch.helpers. * 
È o 


bulk size 


在 配置 bulk 数据 的 时 候 ， 一 般 需 要 注意 的 就 是 请 求 体 大 小 (bulk size) » 


这 里 有 一 点 细节 上 的 了 矛盾， 我 们 知道 ，HTTP 请 求 ， 是 可 以 通过 HTTP 状态 码 100 

Continue 来 持续 发 送 数 据 的 。 但 对 于 ES 节点 接收 HTTP 请 求 体 的 Content- 

Length 来 说 ， 是 按照 整个 大 小 来 计算 的 。 所 以 ， 首 先 ， 要 确保 bulk 数据 不 要 超过 
http.max_content_length 设置 。 


那么 ， 是 不 是 尽量 让 bulk size 接近 这 个 数值 呢 ?当然 不 是 。 


依然 是 请 求 体 的 问题 ， 因 为 请 求 体 需 要 全 部 加 载 到 内 存 ， 而 JVM Heap 一 共 就 那么 
多 ( 按 31GB 算 )， 过 大 的 请 求 体 ， 会 挤占 其 他 线程 池 的 空间 ， 反 而 导致 写 入 性 能 的 
下 降 。 


再 考虑 风 > 磁盘 转速 的 问题 ， 所 以 一 般 来 说 ， 建 议 bulk 请 求 体 的 大 小 ， 在 
15MB 左右 ， 通 过 实际 测试 继续 向 上 探索 最 合适 的 设置 。 


注意 : 这 里 说 的 15MB 是 请 求 体 的 字 节 数 ， 而 不 是 程序 里 里 设置 的 bulk size » bulk 
size 一 般 指数 据 的 条 目 数 。 不 要 忘 了 ，bulk 请 求 体 中 ， 每 条 数据 还 会 额外 带 上 一 行 
元 JSON。 


以 logstash 默认 的 bulk size => 5000 为 例 ， 假 设 单条 数据 平均 大 小 200B ， 
一 次 bulk 请 求 体 的 大 小 就 是 1.5MB。 那 么 我 们 可 以 尝试 bulk size => 

50000 ; 而 如 果 单 条 数据 平均 大 小 是 20KB， 一 次 bulk 大 小 就 是 100MB > PRE 
标 了 ， 需 要 尝试 下 调 至 bulk size => 500 ° 


gateway 


gateway 是 ES 设计 用 来 长 期 存储 索引 数据 的 接口 。 一 般 来 说 ， 大 家 都 是 用 本 地 磁 
盘 来 存储 索引 数据 ， 即 gateway.type 为 local 。 
数据 恢复 中 ， 有 很 多 策略 调整 我 们 已 经 在 之 前 分 片 控制 小 节 讲 过 。 除 开 分 片 级 别 的 
控制 以 外 ，gateway 级 别 也 还 有 一 些 可 优化 的 地 方 : 
e gateway.recover after nodes 该 参数 控制 集群 在 达到 多 少 个 节点 的 规模 后 ， 才 
开始 数据 恢复 任务 。 这 样 可 以 避免 集群 自动 发 现 的 初期 ， 分 片 不 全 的 问题 。 
e gateway.recover after time 该 参数 控制 集群 在 达到 上 条 配置 设置 的 节点 规模 
后 ， 再 等 待 多 久 才 开始 数据 恢复 任务 。 
。 gateway.expected_nodes 该 参数 设置 集群 的 预期 节点 总 数 。 在 达到 这 个 总 数 
后 ， 即 认为 集群 节点 已 经 完全 加 载 ， 即 可 开始 数据 恢复 ， 不 用 再 等 待 上 条 设置 
的 时 间 。 
注意 : gateway 中 说 的 节点 ， 仅 包括 主 节点 和 数据 节点 ， 纯 粹 的 client 节点 是 不 算 
在 内 的 。 如 果 你 有 更 明确 的 选择 ， 也 可 以 按 需 求 写 : 
e gateway.recover_after_data_nodes 
e gateway.recover_after_master_nodes 


e gateway.expected data nodes 
e gateway.expected master nodes 


共享 存储 上 的 影子 副本 


虽然 ES 对 gateway 使 用 NFS，iscsi 等 共享 存储 的 方式 极力 反对 ， 但 是 对 于 较 大 
量 级 的 索引 的 副本 数据 ，ES 从 1.5 版 本 开始 ， 还 是 提供 了 一 种 节约 成 本 又 不 特别 
影响 性 能 的 方式 : 影子 副本 (shadow replica) ° 


首先 ， 需 要 在 集群 各 节点 的 elasticsearch.yml 中 开启 选项 : 


node.enable custom paths: true 


同时 ， 确 保 各 节点 使 用 相同 的 路 径 挂 载 了 共享 存储 ， 且 目录 权限 为 Elasticsearch 
进程 用 户 可 读 可 写 。 


然后 ， 创 建 索引 : 


# curl -XPUT 'http://127.0.0.1:9200/my index' -d ' 


{ 
"index" : { 
"number_of_shards" : 1, 
"number_of_replicas" : 4, 
"data_path": "/var/data/my_index", 
"shadow_replicas": true 
} 
局 


针对 shadow replicas * ES 节点 不 会 做 实际 的 索引 操作 ， 而 是 单纯 的 每 次 flush 
时 ， 把 segment A È fsync 到 共享 存储 磁盘 上 。 然 后 refresh 让 其 他 节点 能 够 搜索 
该 segment 内 容 。 


如 果 你 已 经 决定 把 数据 放 到 共享 存储 上 了 ， 采 用 shadow replicas 还 是 有 一 些 好 处 
的 : 


1. 可 以 帮助 你 节省 一 部 分 不 必要 的 多 副本 分 片 的 数据 写 入 压力 ; 
2. 在 节点 出 现 异 常 ， 需 要 在 其 他 节点 上 恢复 副本 数据 的 时 候 ， 可 以 避免 不 必要 的 
网 络 数据 找 贝 。 


但 是 请 注意 : 主 分 片 节点 还 是 要 承担 一 个 副本 的 写 入 过 程 ， 并 不 像 Lucene 的 
FileReplicator 那样 通过 复制 文件 完成 ， 所 以 达 不 到 完全 节省 CPU 的 效果 。 
shadow replicas 只 是 一 个 在 某 些 特定 环境 下 有 用 的 方式 。 在 资源 允许 的 情况 下 ， 


还 是 应 该 使 用 local gateway。 而 另外 采用 snapshot 接口 来 完成 数据 长 期 备份 到 
HDFS 或 其 他 共享 存储 的 需要 。 


集群 状态 维护 


我 们 都 知道 ，ES 中 的 master 跟 一 般 MySQL ` Hadoop 的 master 是 不 一 样 的 。 它 
即 不 是 写 入 流量 的 唯一 入 口 ， 也 不 是 所 有 数据 的 元 信息 的 存放 地 点 。 所 以 ， 一 般 来 
说 ，ES 的 master 节点 负载 很 轻 ， 集群 性 能 是 可 以 近似 认为 随 着 data 节点 的 扩展 
线性 提升 的 。 


但 是 ， 上 面 这 名 话 并 不 是 完全 正确 的 。 
ES 中 有 一 件 事情 是 只 有 master 节点 能 管理 的 ， 这 就 是 集群 状态 (cluster state)。 
集群 状态 中 包括 以 下 信息 : 


e 集群 层面 的 设置 

e 集群 内 有 哪些 节点 

e 各 索引 的 设置 ， 映 射 ， 分 析 器 和 别名 等 
e 索引 内 各 分 片 所 在 的 节点 位 置 


这 些 信息 在 集群 的 任意 节点 上 都 存放 着 ， 你 也 可 以 通过 / cluster/state 接口 
直接 读 取 到 其 内 容 。 注 意 这 最 后 一 项 信息 ， 之 前 我 们 已 经 讲 过 么 通过 简单 地 
取 余 知道 一 条 数据 放 在 哪个 分 片 里 ， 加 上 现在 分 在 哪个 节点 
上 ， 那 么 ， 整 个 集群 里 ， 任 意 节点 都 可 以 知道 一 条 数据 在 哪个 节点 上 存储 了 。 所 
以 ， 数 据 读 写 才 可 以 发 送 给 集群 里 任意 节点 。 


至 于 修改 ， 则 只 能 由 master 节点 完成 ! 显然， 集群 状态 里 大 部 分 内 容 是 极 少 变动 
的 ， 唯 独 有 一 样 除外 一 一 索引 的 映射 。 因 为 ES 的 schema-less 特性 ， 我 们 可 以 任 
3X5 X JSON 数据 ， 所 以 索引 中 随时 可 能 增加 新 的 字段 。 这 个 时 候 ， 负 责 容 纳 这 条 
ibl A ee ON MM 将 字段 的 映射 结果 传递 给 master 节 

点 ; master 节点 合并 这 段 修改 到 集群 状态 里 ， 发 送 新 版 本 的 集群 状态 到 集群 的 所 有 
节点 上 。 然 后 写 入 操作 才 会 继续 。 一 般 来 说 ， 这 个 操作 是 在 一 二 十 毫秒 内 就 可 以 完 
成 ， 影 响 也 不 大 。 


但 是 也 有 一 些 情况 会 是 例外 。 


批量 新 索引 创建 


在 较 大 规模 的 Elastic Stack 应 用 场景 中 ， 这 是 比较 常见 的 一 个 情况 。 因 为 Elastic 
Stack 建议 采用 日 期 时 间作 为 索引 的 划分 方式 ， 所 以 定时 (一 般 是 每 天 )， 会 统一 产 
生 一 批 新 的 索引 。 而 前 面 已 经 讲 过 ，ES 的 集群 状态 每 次 更 新 都 是 阻塞 式 的 发 布 到 
全 部 节点 上 以 后 ， 节 点 才能 继续 后 续 处 理 。 


这 就 意味 着 ， 如 果 在 集群 负载 较 高 的 时 候 ， 批 量 新 建新 索引 ， 可 能 会 有 一 个 显著 的 
阻塞 时 间 ， 无 法 写 入 任何 数据 。 要 等 到 全 部 节点 同步 完成 集群 状态 以 后 ， 数 据 写 入 
才能 恢复 。 


不 巧 的 是 ， 中 国 使 用 的 是 北京 时 间 ，UTC +0800。 也 就 是 说 ， 默 认 的 Elastic Stack 
新 建 索引 时 间 是 在 早上 8 点 。 这 个 时 间 点 一 般 日 志 写 入 量 已 经 上 涨 到 一 定 水 平 了 
(当然 ， 晚 上 0 点 的 量 其 实 也 不 低 )。 


对 此 ， 可 以 通过 定时 任务 ， 每 天 在 最 低谷 的 早上 三 四 点 ， 提 前 通过 POST mapping 
的 方式 ， 创 建 好 之 后 几 天 的 索引 。 就 可 以 避免 这 个 问题 了 。 


如 果 你 的 日 志 是 比较 严重 的 非 结 构 化 数据 ， 这 个 问题 在 2.0 版 本 后 会 变 得 更 加 严 
重 。Elasticsearch 从 2.0 版 本 开始 ， 对 mapping 更 新 做 了 重 构 。 为 了 防止 字段 类 
型 冲突 和 减少 master 定期 下 发 全 量 cluster state 导致 的 大 流量 压力 ， 新 的 实现 和 
日 实 现 的 区 别 在 : 


e 过 去 : 每 次 bulk 请 求 ， 本 地 生成 索引 后 ， 将 更 新 的 mapping， 按 照 _type 
为 单位 构成 mapping 更 新 请 求 发 给 master ; 

e 现在 : 每 次 bulk 请 求 ， 遍 历 每 条 数据 ， 将 每 条 数据 要 更 新 的 mapping， 都 单 
独 发 给 master， 等 到 master 通知 完全 集群 ， 本 地 才能 生成 这 一 条 数据 的 索 
引 。 


也 就 是 说 ， 一 旦 你 日 志 中 字段 数量 较 多 ， 在 新 创建 索引 的 一 段 时 间 内 ， 可 能 长 达 几 
十 分 钟 一 直 被 反复 锁 死 ! 


过 多 字段 持续 更 新 


是 另 一 种 常见 的 滥用 。 在 使 用 Elastic Stack 处 理 访 问 日 志 时 ， 为 了 查询 更 方便 ， 
能 会 采用 logstash-filter-kv 插件 ， 将 访问 日 志 中 的 每 个 URL 参数 ， 都 切 分 成 单独 
的 字段 。 比 如 一 个 Windex.do?uid=1234567890&action=payload" 的 URL 会 被 转换 
成 如 下 JSON : 


"urlpath" : "/index.do", 


"urlargs" : { 
"uid" : "1234567890", 
"action" : "payload", 


但 是 ， 因 为 集群 状态 是 存在 所 有 节点 的 内 存 里 的 ， 一 旦 URL 参数 过 多 ，ES 节点 的 
内 存 就 被 大 量 用 于 存储 字段 映射 内 容 。 这 是 一 个 极 大 的 浪费 。 如 果 碰 上 URL 参数 
的 键 内 容 本 身 一 直 在 变动 ， 直 接 撑 爆 ES 内 存 都 是 有 可 能 的 ! 


以 上 是 申 实 发 生 的 事件 ， 开 发 人 员 英 名 的 选择 将 一 个 UUID 结果 作为 key 放 在 URL 
参数 里 。 直 接 导致 ES 集群 master 节点 全 部 OOM 。 


如 果 你 在 ES 日 志 中 一 直 看 到 有 新 的 updating mapping [logstash- 
2015.06.01] 字样 出 现 的 话 ， 请 郑重 考虑 一 下 自己 是 不 是 用 的 上 如 此 细 分 的 字段 
列表 吧 o 

好 ， 三 秒 钟 过 去 ， 如 果 你 确定 一 定 以 及 肯定 还 要 这 么 做 ， 下 面 是 一 个 变通 的 解决 办 
法 。 


nested object 


用 nested object 来 存放 URL 参数 的 方法 稍微 复杂 ， 但 还 可 以 接受 。 单 从 JSON X 
据 层 面 看 ， 新 方式 的 数据 结构 如 下 : 


"urlargs": [ 
{ "key": "uid", "value": "1234567890" }, 
{ "key": "action", "value": "payload" }, 


没 错 ， 看 起 来 就 是 一 个 数组 。 但 是 JSON 数组 在 ES 里 是 有 两 种 处 理 方式 的 。 


如 果 直 接 写 入 数组 ，ES 在 实际 索引 过 程 中 ， 会 把 所 有 内 容 都 平 铺 开 ， 变 成 Arrays 
of Inner Objects。 整 条 数据 实际 类 似 这 样 的 结构 : 


"urlpath" : ["/index.do"], 
"urdargsskey : ["uid", “action", ...], 
"urlargs.value" : ["1234567890", "payload", ...] 


这 种 方式 最 大 的 问题 是 ， 当 你 采用 urlargs.key:"uid" AND 
urlargs.value:"0987654321" 语句 意图 搜索 一 个 uid=0987654321 的 请 求 时 ， 
实际 是 整个 URL 参数 中 任意 一 处 value 为 0987654321 的 ， 都 会 命中 。 


要 想 达 到 正确 搜索 的 目的 ， 需 要 在 写 入 数据 之 前 ， 指 定 urlargs 字段 的 映射 类 型 为 
nested object » #7440 T : 


curl -XPOST http://127.0.0.1:9200/logstash-2015.06.01/_mapping - 


d '{ 
"accesslog" : { 
"properties" : { 
"rdargs wt 
"type" : "nested", 
"properties" : ( 
"key" : ( "type" : "string", "index" : "not analyzed 
", "doc values" : true }, 
"value" : ( "type" : "string", "index" : "not analyz 
ed", "doc values" : true } 
} 
} 
} 
} 
o 


这 样 ， 数 据 实 际 是 类 似 这 样 的 结构 : 


"urlpath" : ["/index.do"], 


"urlargs.key" : ["uid"], 
"urlargs.value" : ["1234567890"], 


tr 
1 
"urlargs.key" : ["action"], 
"urlargs.value" : ["payload"], 
y 


4 f& * nested object 节省 字段 映射 的 优势 对 应 的 是 它 在 使 用 的 复杂 。Query 和 
Aggs 都 必须 使 用 专门 的 nested query 和 nested aggs 才能 正确 读 取 到 它 。 


nested query 语法 如 下 : 


curl -XPOST http://127.0.0.1:9200/logstash-2015.06.01/accesslog/ 


_search -d ' 
{ 
"query": { 
"bool": { 
"must": [ 
{ "match": { "urlpath" : "/index.do" }}, 
{ 
"nested": { 
"path": "urlargs", 
"query": { 
"bool": { 
"must": [ 
{ "match": { "urlargs.key": "uid" }}, 
{ "match": { "urlargs.value": "1234567890" }} 
] 
3333 
] 
juu 


nested aggs 语法 如 下 : 


curl -XPOST http://127.0.0.1:9200/logstash-2015.06.01/accesslog/ 
_search -d ' 
{ 
"aggs": { 
"topnuid": { 
"nested": { 
"path": "urlargs" 
tr 
"aggs": { 
"uid": { 
iy Ibbertisr 
"term": { 
"urlargs.key": "uid", 
} 
tr 
"aggs": { 
ODE ea 
"terms": { 
"field": "urlargs.value" 


缓存 


ES 内 针对 不 同 阶段 ， 设 计 有 不 同 的 缓存 。 以 此 提升 数据 检索 时 的 响应 性 能 。 主 要 
包括 节点 层面 的 filter cache 和 分 片 层面 的 request cache。 下 面 分 别 讲述 。 


filter cache 


ES 的 query DSL 在 2.0 版 本 之 前 分 为 query ff» filter 两 种 ， 很 多 检索 语法 ， 是 同时 
存在 query fe filter 里 的 。 比 如 最 常用 的 term ^ prefix ` range 等 。 怎 么 选择 是 使 用 
query 还 是 filter 成 为 很 多 用 户头 疼 的 难题 。 于 是 从 2.0 版 本 开始 ，ES 干脆 合并 了 
filter 统一 归 为 query。 但 是 具体 的 检索 语法 本 身 ， 依 然 有 query 和 filter 上 下 文 的 
区 别 。ES 依靠 这 个 上 下 文 判 断 ， 来 自动 决定 是 否 启 用 filter cache ° 
query 跟 filter 上 下 文 的 区 别 ， 简 单 来 说 : 

e query 是 要 相关 性 评分 的 ，filter FZ; 

e query 结果 无 法 缓存 ，filter 可 以 。 
所 以 ， 选 择 也 就 出 来 了 : 

e 全 文 搜索 、 评 分 排序 ， 使 用 query ; 

e 是 非 过 滤 ， 精 确 匹 配 ， 使 用 filter 。 


不 过 我 们 要 怎么 写 ， 才 能 让 ES 正确 判断 呢 ? 看 下 面 这 个 请 求 : 


# curl -XGET http://127.0.0.1:9200/_search -d ' 


{ 
"query": { 
"bool": { 
"must_not": [ 
{ "match": { "title": "Search" } } 
], 
"must": [ 
{ "match": { "content": "Elasticsearch" } } 
], 
peers T 
{ "term": { "status": "published" } }, 
{ "range": ( "publish date": ( "gte": "2015-01-0 
qe de y 
] 
} 
} 
r' 


在 这 个 请 求 中 ， 

1. ES 先 看 到 一 个 query， 那 么 进入 query 上 下 文 。 

2. 然后 在 bool 里 看 到 一 个 must_not， 那 么 改进 入 filter 上 下 文 ， 这 个 有 关 title 
字段 的 查询 不 参与 评分 。 

3. 然后 接着 是 一 个 must 的 match， 这 个 又 属于 query 上 下 文 ， 这 个 有 关 
content 字段 的 查询 会 影响 评分 。 

4. 最 后 碰 到 filter， 还 属于 filter 上 下 文 ， 这 个 有 关 status 和 publish. date 字段 的 
查询 不 参与 评分 。 


需要 注意 的 是 ，filter cache 是 节点 层面 的 缓存 设置 ， 每 个 节点 上 所 有 数据 在 响应 请 
求 时 ， 是 共用 一 个 缓存 空间 的 。 当 空间 用 满 ， 按 照 LRU 策略 淘汰 掉 最 冷 的 数据 。 


可 以 用 indices.cache.filter.size 配置 来 设置 这 个 缓存 空间 的 大 小 ， 默 认 是 
JVM 2&&j 10%， 也 可 以 设置 一 个 绝对 值 。 注 意 这 是 一 个 静态 值 ， 必 须 在 
elasticsearch.yml 中 提前 配置 。 


shard request cache 


S 还 有 另 一 个 分 片 层 面 的 缓存 ， 叫 shard request cache » 5.0 之 前 的 版 本 中 ， 
request cache 的 用 途 并 不 大 ， 因 为 query cache 要 起 作用 ， 还 有 几 个 先决 条 件 : 


1. 分 片 数 据 不 再 变动 ， 也 就 是 对 当天 的 索引 是 无 效 的 (如 果 refresh interval 
很 大 ， 那 么 在 这 个 间隔 内 倒 也 算 有 效 ) ; 

2. 使 用 了 "now" 语法 的 请 求 无 法 被 缓存 ， 因 为 这 个 是 要 即时 计算 的 ; 

3. 缓存 的 键 是 请 求 的 整个 ISON 字符 串 ， 整 个 字符 串 发 生 任 何 字 节 变 动 ， 缓 存 都 
无 效 。 


以 Elastic Stack 场景 来 说 ，Kibana 里 几乎 所 有 的 请 求 ， 都 是 有 @timestamp 作 
为 过 滤 条 件 的 ， 而 且 大 多 数 是 以 最 近 N 小 时 /分 钟 这 样 的 选项 ， 也 就 是 说 ， 页 面 每 
次 刷新 ， 发 出 的 请 求 ISON 里 的 时 间 过 滤 部 分 都 是 在 变动 的 。query cache 在 处 理 
Kibana 发 出 的 请 求 时 ， 完 全 无 用 。 


而 5.0 版 本 的 一 大 特性 ， 叫 instant aggregation。 解 决 了 这 个 先决 条 件 的 一 大 阻 


碍 。 


在 之 前 的 版 本 ，Elasticsearch 接收 到 请 求 之 后 ， 求 原 样 转发 给 各 分 片 ， 由 
各 分 片 所 在 的 节点 自行 完成 请 求 的 解析 ， 进 行 实际 的 搜索 操作 。 所 以 缓存 的 键 是 原 
始 JSON 串 。 


而 5.0 的 重 构 后 ， 接 收 到 请 求 的 节点 先 把 请 求 的 解析 做 完 ， 发 送 到 各 节点 的 是 统一 
拆 分 修改 好 的 请 求 ， 这 样 就 不 再 担心 JSON 串 多 个 空格 啥 的 了 。 


其 次 ， 上 面 说 的 『 拆 分 修改 」 是 怎么 回 事 呢 ? 


比如 ， 我 们 在 Kibana 里 搜索 一 个 最 近 7 天 ( @timestamp:["now-7d" TO 

"now"] ) 的 数据 ，ES 就 可 以 根据 按 天 索引 的 判断 ， 知 道 从 6 天 前 到 昨天 这 5 个 索 
引 是 肯定 全 履 盖 的 。 那 么 这 个 横 跨 7 天 的 date range query 就 变 成 了 5 个 
match all query 加 2 个 短 时 间 的 date range query» 


现在 你 的 仪表 盘 过 5 分 钟 自 动 刷 新 一 次 ， 再 提交 上 来 一 次 最 近 7 天 的 请 求 ， 中 间 这 
5 match all 就 完全 一 样 了 ， 直 接 从 request cache 返回 即 可 ， 需 要 重新 请 求 
> RA AMAKAEE RAH date range 了 。 


iif: match all 不 用 遍历 倒 排 索引 ， 比 直接 查询 @timestamp: 要 快 很 多 。* * 
注 2 : 判断 覆盖 修改 为 match_all HTA ARR RIAIR” mÆ ES 从 2.x 开始 提供 
的 field stats 接口 可 以 直接 获取 到 @timestamp 在 本 索引 内 的 max/min 值 。 当 然 
从 概念 上 如 此 理解 也 是 可 以 接受 的 。* 


field stats 接口 


curl -XGET "http://localhost:9200/1logstash-2016.11.25/ field sta 
ts?fields-timestamp" 


响应 结果 如 下 : 
{ 
"shards": { 
wt aust d. 
"successful": 1, 
"Failed": 0 
tr 


"indices": { 
"logstash-2016.11.25": ( 
"fields": { 
"timestamp": { 
"max_doc": 1326564, 
"doc_count": 564633, 
"density": 42, 
"sum_doc_freq": 2258532, 
"sum_total_term_freq": -1, 
"min value": "2008-08-01T16:37:51.513Z", 
"max value": "2013-06-02T03:23:11.593Z", 
"is searchable": "true", 
"is aggregatable": "true" 


和 filter cache — 4€ > request cache 的 大 小 也 是 以 节点 级 别 控制 的 ， 配 置 项 名 为 


indices.requests.cache.size ， 其 默认 值 为 1% ° 


字段 数据 


字段 数据 (fielddata)， 在 Lucene 中 又 叫 uninverted index。 我 们 都 知道 ， 搜 索引 擎 
会 使 用 倒 排 索引 (inverted index) 来 映射 单词 到 文档 的 ID 号 。 而 同时 ， 为 了 提供 对 
文档 内 容 的 聚合 ，Lucene 还 可 以 在 运行 时 将 每 个 字段 的 单词 以 字典 序 排 成 另 一 个 
uninverted index， 可 以 大 大 加 速 计 算 性 能 。 

作为 一 个 加 速 性 能 的 方式 ，fielddata 当然 是 被 全 部 加 载 在 内 存 的 时 候 最 为 有 效 。 这 
也 是 ES 默认 的 运行 设置 。 但 是 ， 内 存 是 有 限 的 ， 所 以 ES 同时 也 需要 提供 对 
fielddata 内 存 的 限额 方式 : 


e indices.fielddata.cache.size 节点 用 于 fielddata 的 最 大 内 存 ， 如 果 fielddata 达 
到 该 阅 值 ， 就 会 把 旧 数 据 交 换 出 去 。 该 参数 可 以 设置 百分比 或 者 绝对 值 。 默 认 
设置 是 不 限制 ， 所 以 强烈 建议 设置 该 值 ， 比 如 10% © 

e indices.fielddata.cache.expire 进入 fielddata 内 存 中 的 数据 多 久 自 动 过 期 。 注 
意 ， 因 为 ES 的 fielddata 本 身 是 一 种 数据 结构 ， 而 不 是 简单 的 缓存 ， 所 以 过 期 
删除 fielddata 是 一 个 非常 消耗 资源 的 操作 。ES 官方 在 文档 中 特意 说 明 ， 这 个 
参数 绝对 绝对 不 要 设置 | 


Circuit Breaker 


Elasticsearch 在 total > fielddata > request 三 个 层面 上 都 设计 有 circuit breaker 以 
保护 进程 不 至 于 发 生 OOM 事件 。 在 fielddata 层面 ， 其 设置 为 : 
e indices.breaker.fielddata.limit 默认 是 JVM 堆 内 存 大 小 的 60%。 注意 ， 为 了 让 
设置 正常 发 挥 作 用 ， 如 果 之 前 设置 过 indices.fielddata.cache.size 
的 ， 一 定 要 确保 indices.breaker.fielddata.limit 的 值 大 于 
indices.fielddata.cache.size 的 值 。 否 则 的 话 ，fielddata 大 小 一 到 limit 
阅 值 就 报错 ， 就 永远 道 不 了 size 阅 值 ， 无 法 触发 对 昌 数 据 的 交换 任务 了 。 


doc values 


但 是 相 比 较 集 群 庞 大 的 数据 量 ， 内 存 本 身 是 远 远 不 够 的 。 为 了 解决 这 个 问题 ，ES 
引入 了 另 一 个 特性 ， 可 以 对 精确 索引 的 字段 ， 指 定 fielddata 的 存储 方式 。 这 个 配置 


项 叫 : doc values 。 


所 谓 doc values ， 其 实 就 是 在 ES 将 数据 写 入 索引 的 时 候 ， 提 前 生成 好 
fielddata 内 容 ， 并 记录 到 磁盘 上 。 因 为 fielddata 数据 是 顺序 读 写 的 ， 所 以 即使 在 磁 
盘 上 ， 通 过 文件 系统 层 的 缓存 ， 也 可 以 获得 相当 不 错 的 性 能 。 


注意 : 因为 doc values 是 在 数据 写 入 时 即 生成 内 容 ， 所 以 ， 它 只 能 应 用 在 精准 
索引 的 字段 上 ， 因 为 索引 进程 没 法 知道 后 续 会 有 什么 分 词 器 生成 的 结果 。 


由 于 在 Elastic Stack 22 € * * doc values 的 使 用 极其 频繁 ， 到 Elasticsearch 
5.0 以 后 ， 这 两 者 的 区 别 被 彻底 强化 成 两 个 不 同 字段 类 型 : text 和 keyword ° 


"myfieldname": { 
"type" : "text" 


等 同 于 过 去 的 : 

"myfieldname": { 
"type": "string", 
"fielddata": false 

而 


"myfieldname": { 
"type": "keyword" 


等 同 于 过 去 的 : 


"myfieldname": { 
"type": "string", 
"index": "not_analyzed", 
"doc_values": true 


也 就 是 说 ， 以 后 的 用 户 ， 已 经 不 太 需 要 在 意 fielddata 的 问题 了 。 不 过 依然 有 少数 情 
况 ， 你 会 需要 对 分 词 字段 做 聚合 统计 的 话 ， 你 可 以 在 自己 接受 范围 内 ， 开 局 这 个 特 
pH: 


{ 
"mappings": { 
"my_type": { 
"properties": { 
"message": { 
"type": "text", 
"fielddata": true, 
"fielddata_frequency_filter": { 
vinee Ol 
"max": 1.0, 
"min_segment_size": 500 
} 
} 
} 
} 
} 
} 


你 可 以 看 到 在 上 面 加 了 一 段 fielddata frequency filter 配置 ， 这 个 配置 是 
segment 级 别 的 。 上 面 示例 的 意思 是 : 只 有 这 个 segment 里 的 文档 数量 超过 500 
个 ， 而 且 含 有 该 字段 的 文档 数量 占 该 Segment 里 的 文档 数量 比例 超过 10% 时 ， 才 
加 载 这 个 segment 的 fielddata ° 


下 面 是 一 个 可 能 有 用 的 对 分 词 字段 做 聚合 的 示例 : 


curl -XPOST 'http://localhost :9200/logstash-2016.07.18/logs/_sea 
rch?pretty&terminate_after=10000&size=0' -d ' 


"aggs": { 
"group": { 
"terms": { 
"field": "punct" 
tr 
"aggs": { 
"keyword": { 
"significant terms": { 
Sq zo s 2. 
"field": "message" 
tr 
"aggs": { 
dauert 
Mi cio) che gab he E 
" source": { 
"include": [ "message" ] 
tr 
"size":1 
} 
} 
} 
} 
} 
} 
} 
} 


这 个 示例 可 以 对 经 过 了 logstash-filter-punct 插件 处 理 的 数据 ， 获 取 每 种 
punct 类 型 日 志 的 关键 词 和 对 应 的 代表 性 日 志 原 文 。 其 效果 类 似 Splunk 的 事件 模式 


功能 : 


fielddata 


splunk 


mR BEANA RR Li DII. Search & Reporting 


Q 新 搜索 另存 为 v 关闭 










index="_internal” | 所 有 时 间 v Q 
x 
z 13,365 个 事件 (16/05/31 18:22:05.000 之 前 ) No Event Sampling v 任务 v "s ^» 6 i 9 详细 模式 v 
事件 (13365) ax wie 可 视 化 





19 模式 基于 13,365 个 事件 示例 预计 的 事件 x 
3 . 6 3 K 

16.83% <i} Rt> INFO Metrics - group=queue, name=typingqueue, max_size_kb=500, current_size_kb=0, current_size=0, largest_size=4, smallest. Base 

size=0 
15.2% «i3» INFO Metrics - group=per_sourcetype_thruput, series="splunkd_ui_access", kbps=0.331398, eps=0.741929, kb= 10.273438, ev=2 index="_internal" pipeline 
3, avg. age-0 739130, max age-1 Ripah tigi 创建 告警 
7.9% 127.0.0.1 - admin [< 时 间 融 >] "GET /zh-CN/splunkd/_raw/services/messages?output_mode=json&sort_key=timeCreated_epochSecs&sort 包括 关键 字 

_diredesc&count= 1000&_* 1464689338995 HTTP/1.1 200 296 "http://localhost;8000/zh-CN/app/search/search?q*search %20index%3 pipeline 


D%22_internal%22%20%7C%20typelearner&display page search mode-verbose&dispatch.sample ratio- 1&earliest-&latest-&display.pag 


5.18% — «iH 19 RE» INFO Metrics - group» deploy-server, nameclients, phonehome, nReceived=0 


3.88% <i} Rt> INFO Metrics - group=thruput, name-thruput, instantaneous, kbps» 1 . 143293, instantaneous, eps*3.709647, average kbps 1.07 
3732, total k processed» 5758.000000, kb=35.442383, ev= 1 15.000000, load average-2 088379 


259* «iili» INFO Metrics - group=tpool, namezindexertpool, qsize=0, workers=2, qwork_units=0 


259% <AR> INFO Metrics - group=tailingprocessor, name=tailreader0, current. queue sizes0, max queue. size-2, files queued- 18, new. files 
-queued=0 fd. cache size-2 


1.56% «i198» INFO Metrics - groupssearch. health metrics, name*compute. search, quota, compute. search. quota, max ms*3, compute sear 
ch quota mean ms-2.000000 


1.38% «0/98.» INFO Metrics - group=search_concurrency, user=admin, active hist searches» 1, active_realtime_searches=0 


i 1.29% «inis» INFO Metrics - arouo-mnool. max used interval=26649. max used-359383. ava rsv-440. capacitv- 536870912. used-2738. reo 
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curator 


如 果 经 过 之 前 章节 的 一 系列 优化 之 后 ， 数 据 确 实 超过 了 集群 能 承载 的 能 力 ， 除 了 拆 
分 集群 以 外 ， 最 后 就 只 剩 下 一 个 办 法 了 : ARR RA o 


为 了 更 加 方便 的 做 清除 数据 ， 合 并 segment， 备 份 恢复 等 管理 任务 ，Elasticsearch 
在 提供 相关 API 的 同时 ， 另 外 准备 了 一 个 命令 行 工具 ， 叫 curator ° curator 是 
Python 程序 ， 可 以 直接 通过 pypi 库 安装 : 


pip install elasticsearch-curator 


注意 ， 是 elasticsearch-curator 不 是 curator ° PyPi 原先 就 有 另 一 个 项 目 叫 这 个 名 
字 


参数 介绍 


fe Elastic Stack 里 其 他 组 件 一 样 ，curator 也 是 被 Elastic.co 收购 的 原 开 源 社区 周 
边 。 收 编 之 后 同样 进行 了 一 次 重 构 ， 命 令 行 参 数 从 单字 母 风格 改 成 了 长 单词 风格 。 
新 版 本 的 curator 命令 可 用 参数 如 下 : 


Usage: curator [OPTIONS] COMMAND [ARGS]... 
Options 包括 : 


--host TEXT Elasticsearch host. --url_prefix TEXT Elasticsearch http url prefix. -- 
port INTEGER Elasticsearch port. --use ssl Connect to Elasticsearch through 
SSL. --http auth TEXT Use Basic Authentication ex: user:pass --timeout 
INTEGER Connection timeout in seconds. --master-only Only operate on elected 
master node. --dry-run Do not perform any changes. --debug Debug mode -- 
loglevel TEXT Log level --logfile TEXT log file --logformat TEXT Log output format 
[default|logstash]. --version Show the version and exit. --help Show this message 
and exit. 


Commands 包括 : alias Index Aliasing allocation Index Allocation bloom Disable 
bloom filter cache close Close indices delete Delete indices or snapshots open 
Open indices optimize Optimize Indices replicas Replica Count Per-shard show 


Show indices or snapshots snapshot Take snapshots of indices (Backup) 


针对 具体 的 Command， 还 可 以 继续 使 用 --help 查看 该 子 命令 的 帮助 。 比 如 查 
看 close 子 命令 的 帮助 ， 输 入 curator close --help ， 结 果 如 下 : 


Usage: curator close [OPTIONS] COMMAND [ARGS]... 
Close indices 


Options: 
--help Show this message and exit. 


Commands: 
indices Index selection. 


常用 示例 


在 使 用 1.4.0 以 上 版 本 的 Elasticsearch 前 提 下 ，curator 曾经 主要 的 一 个 子 命令 
bloom 已 经 不 再 需要 使 用 。 所 以 ， 目 前 最 常用 的 三 个 子 命令 ， 分 别 是 close , 
delete 和 optimize ， 示 例如 下 : 


curator --timeout 36000 --host 10.0.0.100 delete indices --older 
-than 5 --time-unit days --timestring '%Y.%m.%d' --prefix logsta 
sh-mweibo-nginx- 

curator --timeout 36000 --host 10.0.0.100 delete indices --older 
-than 10 --time-unit days --timestring '%Y.%m.%d' --prefix logst 


ash-mweibo-client- --exclude 'logstash-mweibo-client-2015.05.11' 
curator --timeout 36000 --host 10.0.0.100 delete indices --older 
-than 30 --time-unit days --timestring '%Y.%m.%d' --regex '^logs 


tash-mweibo-\d+' 

curator --timeout 36000 --host 10.0.0.100 close indices --older- 
than 7 --time-unit days --timestring '%Y.%m.%d' --prefix logstas 
h- 

curator --timeout 36000 --host 10.0.0.100 optimize --max num seg 
ments 1 indices --older-than 1 --newer-than 7 --time-unit days - 
-timestring '%Y.%m.%d' --prefix logstash- 


ii — E ? 结果 是 : 


logstash-mweibo-nginx-yyyy.mm.dd 索引 保存 最 近 5 X > logstash-mweibo-client- 
yyyy.mm.dd 保存 最 近 10 X > logstash-mweibo-yyyy.mm.dd 索引 保存 最 近 30 X ; 
且 所 有 七 天 前 的 logstash-* 索引 都 暂时 关闭 不 用 ; 最 后 对 所 有 非 当 日 日 志 做 
segment 合并 优化 。 


profiler 


profiler  Elasticsearch 5.0 的 一 个 新 接口 。 通 过 这 个 能 ， 可 以 看 到 一 个 搜索 聚 
合 请 求 ， 是 如 何 拆 分 成 底层 的 Lucene 请 求 ， 并 且 显 示 每 部 分 的 耗 时 情况 。 


启用 profiler 的 方式 很 简单 ， 直 接 在 请 求 里 加 一 行 即 可 : 


curl -XPOST 'http://localhost:9200/ search' -d '( 
"profile": true, 
"query": ( ... }, 
"aggs": ( ... } 

y! 


可 以 看 到 其 中 对 query 和 aggs 部 分 的 返回 是 不 太一 样 的 。 


query 


query 部 分 包括 collectors ` rewrite 和 query 部 分 。 对 复杂 query > profiler 会 拆 分 
query 成 多 个 基础 的 TermQuery， 然 后 每 个 TermQuery 再 显示 各 自 的 分 阶段 耗 时 
如 下 : 


"breakdown": { 
"score": 51306, 
"score_count": 4, 
"build_scorer": 2935582, 
"build scorer count": 1, 
"match": 0, 
"match count": 0, 
"create weight": 919297, 
"create weight count": 1, 
"next doc": 53876, 
"next doc count": 5, 
"advance": 0, 
"advance count": 0 


aggs 


"time": "1124.864392ms", 
"breakdown": { 
"reduce": 0, 
"reduce count": O, 
"build aggregation": 1394, 
"build aggregation count": 150, 
"initialise": 2883, 
"initialize count": 150, 
"collect": 1124860115, 
"collect count": 900 


我 们 可 以 很 明显 的 看 到 聚合 统计 在 初始 化 阶段 、 收 集 阶段 、 构 建 阶段 、 汇 总 阶段 分 
别 花 了 多 少时 间 ， 遍 历 了 多 少数 据 。 


注意 其 中 reduce 阶段 还 没 实现 完毕 ， 所 有 都 是 0。 因 为 目前 profiler 只 能 在 shard 
级 别 上 做 统计 。 


collect 阶段 的 耗 时 ， 有 助 于 我 们 调整 对 应 aggs 的 collect mode 参数 选择 。 目 
前 Elasticsearch 支持 breadth_first 和 depth_first 两 种 方式 。 


initialise 阶段 的 耗 时 ， 有 助 于 我 们 调整 对 应 aggs 的 execution hint 参数 选 
择 。 目 前 Elasticsearch 支持 

map ^ global ordinals low cardinality ^ global ordinals 和 
global ordinals hash 四 种 选择 。 在 计算 离散 度 比 较 大 的 字段 统计 值 时 ， 适 当 
调整 该 参数 ， 有 益 于 节省 内 存 和 提高 计算 速度 。 


对 高 离散 度 字 段 值 统计 性 能 很 关注 的 读者 ， 可 以 关注 
https://github.com/elastic/elasticsearch/pull/21626 这 条 记录 的 进展 。 


扩展 和 测试 方案 


在 体验 完 Elasticsearch 便捷 的 操作 后 ， 下 一 步 一 定 会 碰 到 的 问题 是 : 数据 写 入 变 
慢 了 ， 机 器 变 卡 了 ， 是 需要 做 优化 呢 ? 还 是 需要 扩容 设备 了 ? 如 果 做 扩容 ， 索 引 的 
分 片 和 副本 设置 多 少 才 合 适 ? 如 果 做 优化 ， 某 个 参数 能 造成 什么 样 的 影响 ? 


而 ES 集群 性 能 ， 受 服务 器 硬件 、 数 据 结构 和 长 度 、 请 求 接 口 复 杂 度 等 各 种 环节 影 
响 颇 大 。 这 些 问题 ， 都 需要 有 一 个 标准 的 测试 流程 给 出 答案 。 


由 于 ES 是 近乎 线性 扩展 的 分 布 式 系统 ， 所 以 对 上 述 需求 我 们 都 可 以 总 结 成 同一 个 
测试 模式 : 


. 使 用 和 线 上 集群 相同 硬件 配置 的 服务 器 搭建 一 个 单 节 点 集群 。 

. 使 用 和 线 上 集群 相同 的 映射 创建 一 个 0 副本 ，1 分 片 的 测试 索引 。 

. 使 用 和 线 上 集群 相同 的 数据 写 入 进行 压 测 。 

.观察 写 入 性 能 ， 或 者 运行 查询 请 求 观察 搜索 聚合 性 能 。 

. 持续 压 测 数 小 时 ， 使 用 监控 系统 记录 eps ` requesttime ` fielddata cache ` GC 
count 等 关键 数据 。 


O A O N 一 


测试 完成 后 ， 根 据 监控 系统 数据 ， 确 定单 分 片 的 性 能 拐点 ， 或 者 适合 自己 预期 值 的 
临界 点 。 这 个 数据 ， 就 是 一 个 基准 数据 。 之 后 的 扩容 计划 ， 都 可 以 以 这 个 基准 单位 


需要 注意 的 是 ， 测 试 是 以 分 片 为 单位 的 ， 在 实际 使 用 中 ， 因 为 主 分 片 和 副本 分 片 都 
是 在 各 自 节点 做 indexing 和 merge 操作 ， 需 要 消耗 同样 的 写 入 性 能 。 所 以 ， 实 际 
集群 的 容量 预 估 中 ， 要 考虑 副本 数 的 影响 。 ec ， 假 如 你 在 基准 测试 中 得 到 单 
机 写 入 性 能 在 10000 eps， 那 么 开启 一 个 副本 后 所 能 达到 的 eps 就 只 有 5000 了 。 
还 想 写 入 10000 eps 的 话 ， 就 需要 加 一 倍 机 器 。 


另外 ， 测 试 中 我 们 使 用 的 配置 都 尽量 贴 合 当 前 现状 。 事 实 上 ， 很 多 配置 可 能 其 实 并 
不 合理 。 在 确定 基准 线 并 开始 扩容 之 前 ， 还 是 要 认 丨 调节 配置 ， 审 核 请 求 使 用 的 接 
口 是 否 最 优 ， 然 后 反复 测试 。 然 后 取 一 个 最 终 的 基准 值 。 


审核 请 求 ， 更 是 一 个 长 期 的 过 程 ， 就 像 DBA 永远 需要 关注 慢 查 询 一 样 。ES 的 慢 查 
询 请 求 处 理 ， 请 阅读 稍 后 性 能 日 志 一 节 。 


esrally 测试 工具 


esrally Æ Elastic.co 开源 的 专门 做 Elasticsearch 压 测 的 工具 。 我 们 在 官网 上 看 到 
的 nightly benchmark 结果 就 是 用 这 个 工具 每 晚 运行 生成 的 报告 。 用 这 个 工具 ， 可 
以 很 方便 的 验证 自己 的 代码 修改 、 配 置 调整 对 性 能 的 影响 效果 。 


安装 运行 


esrally 依赖 python3.4+， 所 以 需要 先 安装 好 python 3.5。 然 后 直接 pip3 
install esrally 即 可 。 


被 压 测 的 Elasticsearch 有 两 种 来 源 : 


e 本 机 有 gradle 工具 的 ， 可 以 从 最 新 的 GitHub master 代码 编译 
e 没有 gradle 工具 的 ， 可 以 按 官方 提供 的 标签 ， 下 载 对 应 版 本 的 二 进 制 分 发 包 。 


esrally 在 压 测 完毕 后 ， 可 以 把 指标 数据 写 入 到 另 一 个 ES 索引 中 ， 可 以 很 方便 的 用 
Kibana 。 这 就 需要 另外 配置 一 下 -/.rally/rally.ini 里 
reporting 部 分 的 参数 : 


[reporting] 

datastore.type = elasticsearch 
datastore.host = localhost 
datastore.port = 9200 
datastore.secure = False 
datastore.user = 
datastore.password = 


不 用 担心 这 个 ES 会 跟 一 会 儿 压 测 运行 的 ES 冲突 ， 因 为 压 测 启动 的 ES 会 监听 在 
其 他 端口 上 。 


我 们 先 简单 测试 一 下 标准 的 运行 : : 
/opt/local/Library/Frameworks/Python.framework/Versions/3.5/bin/ 


esrally --pipeline=from-distribution --distribution-version=5.0. 
0 


默认 情况 下 压 测 采 用 的 数据 集 叫 geonames， 是 一 个 2.8GB 大 的 JSON 数据 。ES 
也 提供 了 一 系列 其 他 类 型 的 压 测 数据 集 。 如 果 要 切换 数据 集 采用 --track 参数 : 


/opt/local/Library/Frameworks/Python.framework/Versions/3.5/bin/ 
esrally --pipeline-from-distribution --distribution-version-5.0. 
© --track-geonames 


重复 运行 的 时 候 可 以 修改 -/.rally/rally.ini 里 的 
tracks[default.url] ， 改 为 第 一 次 运行 时 下 载 的 地 址 : 
~/.rally/oenchmarks/tracks/default 。 然 后 采用 离线 参数 重复 运行 : 


/opt/local/Library/Frameworks/Python.framework/Versions/3.5/bin/ 
esrally --offline --pipeline-from-distribution --distribution-ve 
rsion=5.0.0 --track=geonames 


静 静 等 待 程序 运行 完毕 ， 就 会 给 出 一 个 漂亮 的 输出 结果 了 。 


调整 压 测 任务 


ME 云 行 会 是 一 个 很 漫长 的 时 间 ， 如 果 你 其 实 只 关心 部 分 的 性 能 ， 比 如 只 
写 入 ， 不 关心 搜索 。 其 实 可 以 自己 去 修改 一 下 track 的 任务 定义 。 


track 的 定义 文件 在 
-/.rally/benchmarks/tracks/default/geonames/track.json 。 如 果 你 改动 
较 大 ， 建 议 直接 新 建 一 个 track 目录 ， 比 如 叫 mytest/track.json ° 


对 照 geonames 里 的 定义 ， 一 个 track 包括 以 下 部 分 : 


e meta: 定义 数据 来 源 URL ° 

e indices : 定义 索引 名 称 、 索 引 mapping 的 文件 位 置 、 数 据 的 存放 位 置 和 校 验 
信息 。 

e operations : 定义 一 个 个 操作 的 名 称 、 类 型 、 索 引 和 请 求 参 数 。 如 果 操 作 类 型 
是 index， 可 用 的 索引 参数 有 : client 并 发 量 、bulk 大 小 、 是 否 强制 merge 
等 ; 如 果 操 作 类 型 是 search， 可 用 的 请 求 参数 就 是 一 个 queries 数组 ， 按 序 放 
好 一 个 个 queryDSL ° 

e challenges : 定义 好 名 称 和 调用 哪些 operation， 调 用 顺序 如 何 。 


最 后 运行 命令 的 时 候 通过 --challenge= 参数 来 指定 执行 哪个 任务 。 


比如 我 们 只 关心 写 入 不 关心 搜索 ， 打 开 track.json 可 以 看 到 有 这 么 几 个 
challenges : 


"challenges": [ 


{ 
"name": "append-no-conflicts", 
Kde Scripten: ee 
"schedule": [ 
"index-append-default-settings", 
"stats", 
"search" 
] 
tr 
{ 
"name": "append-fast-no-conflicts", 
Ndescrapt ton: c. 
"schedule": [ 
"index-append-fast-settings" 
] 
tr 


我 们 就 知道 了 ， 上 默认 的 append-no-conflicts 是 要 测 完 写 入 再 测 搜索 的 ， 而 
append-fast-no-conflicts 是 只 测 写 入 的 。 那 么 我 们 这 么 运行 就 行 : 


/opt/local/Library/Frameworks/Python.framework/Versions/3.5/bin/ 
esrally --offline --pipeline=from-distribution --distribution-ve 
rsion=5.0.0 --track=geonames --challenge=append-fast-no-conflict 
S 


调整 压 测 数据 


如 果 要 用 自己 的 数据 集 呢 ， 也 一 样 是 在 自己 的 track.json 里 定义 ， 比 如 : 


"meta": { 
"data-url": "/Users/raochenlin/.rally/benchmarks/data/sp 
lunklog/1468766825 10.json.bz2" 


ty 
"indices": [ 
{ 
"name": "splunklog", 
"types": [ 
{ 
"name": "type", 
"mapping": "mappings.json", 
"documents": "1468766825 10.json.bz2", 
"document-count": 924645, 
"compressed-bytes": 19149532, 
"uncompressed-bytes": 938012996 
} 
] 
} 


], 


这 里 就 是 用 的 一 份 splunkd 的 internal A & > JSON 导出 。 字 节 数 大 小 为 
938012996。 压 缩 后 为 19149532 » 


多 集群 连接 


当 你 的 ES 集群 发 展 到 一 定 规模 ， 单 集群 不 足以 应 对 庞大 的 在 线索 引 量 级 ， 或 者 由 
于 业务 隔离 需求 ， 都 有 可 能 划分 成 多 个 集群 。 这 时 候 ， 另 一 个 问题 就 出 来 了 : 可 能 

其 中 有 一 部 分 数据 ， 被 分 割 在 两 个 集群 里 ， 但 是 还 是 需要 一 如 果 是 自己 
写 程 序 ， 当 然 可 以 初始 化 两 个 对 象 ， 分 别 连接 两 个 集群 ， 得 到 结果 集 后 Pita 
并 。 但 是 如 果 用 Elastic Stack #) > Kibana 可 不 支持 同时 连 ME 这 时 
候 ， 就 要 用 到 ES 中 一 个 特殊 的 角色 : tribe 节点 。 


tribe 节点 只 需要 提供 集群 自动 发 现 方面 的 配置 ， 连 接 上 多 个 集群 后 ， 对 外 提供 只 读 
功能 。 elasticsearch.yml 配置 示例 如 下 


tribe: 
1002: 
cluster.name: es1002 
discovery.zen.ping.timeout: 100s 
discovery.zen.ping.multicast.enabled: false 
discovery.zen.ping.unicast.hosts: ["10.19.0.22","10.19.0 
24) 10.19.0221" | 
1003: 
cluster.name: es1003 
discovery.zen.ping.timeout: 100s 
discovery.zen.ping.multicast.enabled: false 
discovery.zen.ping.unicast.hosts: ["10.19.0.97","10.19.0 
.98","10.19.0.99","10.19.0.100"] 
blocks: 
write: true 
metadata: true 
on_conflict: prefer_1003 


注意 这 里 的 on conflict WE > Z £4 4ESEP > R45] ZA P KATA > tribe 
节点 默认 会 把 请 求 轮 询 转 发 到 各 个 集群 上 ， 这 显然 是 不 可 以 的 。 所 以 可 以 设置 一 个 
优先 级 ， 在 索引 名 冲突 的 时 候 ， 偏 向 于 转发 给 某 一 个 集群 。 


VA tribe 配置 启动 的 Elasticsearch 服务 ， 其 日 志 输 入 如 下 : 


[2015-06-18 18:05:51,983][INFO ][node ] [Man 


slaughter] version[1.5.1], pid[12846], build[5e38401/2015-04-09T 


132417352] 

[2015-06-18 18:05:51,984][INFO ][node ] [Man 
slaughter] initializing 

[2015-06-18 18:05:51,990][INFO ][plugins ] [Man 
slaughter] loaded [], sites [] 

[2015-06-18 18:05:54,891][INFO ][node ] [Man 


slaughter/1003] version[1.5.1], pid[12846], build[5e38401/2015-0 
4-09T13:41:35Z] 


[2015-06-18 18:05:54,891][INFO ][node ] [Man 
slaughter/1003] initializing 

[2015-06-18 18:05:54,891][INFO ][plugins ] [Man 
slaughter/1003] loaded [], sites [] 

[2015-06-18 18:05:55,654][INFO ][node ] [Man 
slaughter/1003] initialized 

[2015-06-18 18:05:55,655][INFO ][node ] [Man 


slaughter/1002] version[1.5.1], pid[12846], build[5e38401/2015-0 
4-09T13:41:35Z] 


[2015-06-18 18:05:55,655][INFO ][node ] [Man 
slaughter/1002] initializing 

[2015-06-18 18:05:55,656][INFO ][plugins ] [Man 
slaughter/1002] loaded [], sites [] 

[2015-06-18 18:05:56,275][INFO ][node ] [Man 
slaughter/1002] initialized 

[2015-06-18 18:05:56,285][INFO ][node ] [Man 
slaughter] initialized 

[2015-06-18 18:05:56,286][INFO ][node ] [Man 
slaughter] starting 

[2015-06-18 18:05:56,486][INFO ][transport ] [Man 


slaughter] bound address {inet[/0:0:0:0:0:0:0:0:9301]}, publish. 
address {inet[/10.19.0.100:9301]} 


[2015-06-18 18:05:56,499][INFO ][discovery ] [Man 
slaughter] elasticsearch/Oewo-L2fR3y2xsgpsol40g 

[2015-06-18 18:05:56,499][WARN ][discovery ] [Man 
slaughter] waited for Os and no initial state was set by the dis 
covery 

[2015-06-18 18:05:56,529][INFO ][http ] [Man 


slaughter] bound address {inet[/0:0:0:0:0:0:0:0:9201]}, publish. 
address {inet[/10.19.0.100:9201]} 
[2015-06-18 18:05:56,530][INFO ][node ] [Man 


slaughter/1003] starting 

[2015-06-18 18:05:56,603][INFO ][transport ] [Man 
slaughter/1003] bound address {inet[/0:0:0:0:0:0:0:0:9302]}, pub 
lish address {inet[/10.19.0.100:9302]} 


[2015-06-18 18:05:56,609][INFO ][discovery ] [Man 
slaughter/1003] es1003/m1-cDaFTSoqqyC2iiQhECA 
[2015-06-18 18:06:26,610][WARN ][discovery ] [Man 


slaughter/1003] waited for 30s and no initial state was set by t 
he discovery 


[2015-06-18 18:06:26,610][INFO ][node ] [Man 
slaughter/1003] started 
[2015-06-18 18:06:26,611][INFO ][node ] [Man 
slaughter/1002] starting 
[2015-06-18 18:06:26,674][INFO ][transport ] [Man 


slaughter/1002] bound address {inet[/0:0:0:0:0:0:0:0:9303]}, pub 
lish address {inet[/10.19.0.100:9303]} 


[2015-06-18 18:06:26,676][INFO ][discovery ] [Man 
slaughter/1002] es1002/4FPiRPh7TFyBk-BaPc TLg 
[2015-06-18 18:06:56,676][WARN ][discovery ] [Man 


slaughter/1002] waited for 30s and no initial state was set by t 
he discovery 


[2015-06-18 18:06:56,677][INFO ][node ] [Man 
slaughter/1002] started 

[2015-06-18 18:06:56,677][INFO ][node ] [Man 
slaughter] started 

[2015-06-18 18:07:37,266][INFO ][cluster.service ] [Man 


slaughter/1003] detected master [10.19.0.97][jnA-rt2fS_22Mz9nY15 
Ueg][localhost.localdomain][inet[/10.19.0.97:9300]] (max local st 
orage nodes-1, data-false, master=true}, added {[10.19.0.73][_S8 
ylzi10Tv6Nypi1YoMRNGQ] [esnode073.mweibo.bx.sinanode.com][inet[/10. 
19.0.73:9300]](max local storage nodes-i1, master=false},}, reaso 
n: zen-disco-receive(from master [[10.19.0.97][jnA-rt2fS 22Mz9nY 
l15Ueg][localhost.localdomain][inet[/10.19.0.97:9300]] (max local. 
storage nodes-1, data-false, master-truej]) 

[2015-06-18 18:07:37,382][INFO ][tribe ] [Man 
slaughter] [1003] adding node [[10.19.0.73][. S8ylz10Tv6Nyp1YoMRN 
GQ] [esnode073.mweibo.bx.sinanode.com][inet[/10.19.0.73:9300]] (ma 
x local storage nodes-1, tribe.name=1003, master=false}] 
[2015-06-18 18:07:37,391][INFO ][tribe ] [Man 
slaughter] [1003] adding node [[Manslaughter/1003][m1-cDaFTSoqqy 


C2iiQhECA] [localhost .localdomain] [inet[/10.19.0.100:9302]]{data= 
false, tribe.name-1003, client-true)] 

[2015-06-18 18:07:37,393][INFO ][tribe ] [Man 
slaughter] [1003] adding node [[10.19.0.97][ mIrWKzzTYifpixshngB 
ew] [esnode054.mweibo.bx.sinanode.com][inet[/10.19.0.54:9300]] (ma 
x local storage nodes-1, tribe.name=1003, master-falsej] 


[2015-06-18 18:07: 


slaughter] [1003] 


37,393] [INFO 
adding index 


][tribe 


] [Man 


[logstash-mweibo-vip-2015.06.15] 


[2015-06-18 18:07:37,394][INFO ][tribe ] [Man 
slaughter] [1003] adding index [logstash-php-2015.06.08] 
[2015-06-18 18:07:37,394][INFO ][tribe ] [Man 


slaughter] [1003] 


adding index 


[logstash-mweibo-vip-2015.06.16] 


[2015-06-18 18:07:37,395][INFO ][tribe ] [Man 
slaughter] [1003] adding index [.kibana] 

[2015-06-18 18:07:37,398][INFO ][tribe ] [Man 
slaughter] [1003] adding index [logstash-php-2015.06.14] 
[2015-06-18 18:07:37,403][INFO ][tribe ] [Man 


slaughter] [1003] 


adding index 


[logstash-mweibo-vip-2015.06.10] 


[2015-06-18 18:07:37,403][INFO ][tribe ] [Man 
slaughter] [1003] adding index [kibana-int] 
[2015-06-18 18:07:37,404][INFO ][tribe ] [Man 


slaughter] [1003] 


[2015-06-18 18:07: 


adding index 
37,411] [INFO 


[logstash-mweibo-2015.06.13] 


][cluster.service 


] [Man 


slaughter] added {[10.19.0.73][_S8y1Z10TV6Nyp1YoMRNGQ] [esnode073 
.mweibo.bx.sinanode.com][inet[/10.19.0.73:9300]] (max local stora 
ge nodes-1, tribe.name-1003, master=false}, [10.19.0.97][jnA-rt2f 
S_22Mz9nY15Ueg] [localhost .localdomain] [inet[/10.19.0.97:9300] ] (m 
ax_local_storage_nodes=1, tribe.name=1003, data-false, master=tr 
ue}, }, reason: cluster event from 1003, zen-disco-receive(from m 
aster [[10.19.0.97][jnA-rt2fS_22Mz9nY15Ueg] [localhost .localdomai 
n][inet[/10.19.0.97:9300]] (max local storage nodes-1, data=false 
, master=true}] ) 

[2015-06-18 18:08:07,316][INFO ][cluster.service ] [Man 
slaughter/1002] detected master [10.19.0.22][6qyQh9EURUyO7RBC dX 
Dow][localhost.localdomain][inet[/10.19.0.22:9300]] (max local st 
orage nodes-1, master=true}, added {[10.19.0.93][qAklY08iSsSfIf2 
vvu6eryw][localhost.localdomain][inet[/10.19.0.93:9300]] [max loca 
l storage nodes-1, master=false}]) 

[2015-06-18 18:08:07,350][INFO ][indices.breaker ] [Man 
slaughter/1002] Updating settings parent: [PARENT, type-PARENT, li 


mit=259489792/247.4mb, overhead=1.0], fielddata: [FIELDDATA, type= 
MEMORY, limit-155693875/148.4mb,overhead-1.03], request: [REQUEST 
, type=MEMORY, 1imit-103795916/98.9mb, overhead=1.0] 

[2015-06-18 18:08:07,353][INFO ][tribe ] [Man 
slaughter] [1002] adding node [[10.19.0.93][qAklY08iSsSfIf2vvu6I 
yw][localhost.localdomain][inet[/10.19.0.93:9300]] (max local sto 
rage nodes-1, tribe.name-1002, master=false} | 

[2015-06-18 18:08:07,357][INFO ][tribe ] [Man 
slaughter] [1002] adding node [[Manslaughter/1002][4FPiRPh7TFyBk 
-BaPc_TLg][localhost.localdomain] [inet[/10.19.0.100:9303] ]{data= 
false, tribe.name-1002, client-true)] 

[2015-06-18 18:08:07,358][INFO ][tribe ] [Man 
slaughter] [1002] adding node [[10.19.0.22][tkrBsbnLTryOzzZEdbQR 
OeA][localhost.localdomain][inet[/10.19.0.27:9300]] (max local sto 
rage nodes-1, tribe.name-1002, master=false} | 

[2015-06-18 18:08:07,358][INFO ][tribe ] [Man 
slaughter] [1002] adding index [test.yingjui-mweibo client downs 
tream success-2015.06.07] 

[2015-06-18 18:08:07,363][INFO ][tribe ] [Man 
slaughter] [1002] adding index [logstash-mweibo client downstrea 
m error-2015.06.02] 


[2015-06-18 18:08:07,366][INFO ][tribe ] [Man 
slaughter] [1002] adding index [.kibana 5601] 
[2015-06-18 18:08:07,377][INFO ][cluster.service ] [Man 


slaughter] added [[10.19.0.22][6qyQh9EURUyO7RBC dXbow] [localhost 
.localdomain][inet[/10.19.0.22:9300]] (max local storage nodes-1, 
tribe.name-1002, master=false}, [10.19.0.93][17nkk-H7S6GvMzWwGeo 
_CA][localhost.localdomain][inet[/10.19.0.93:9300]]{max_local_st 
orage nodes-1, tribe.name-1002, master=false},}, reason: cluster 
event from 1002, zen-disco-receive(from master [[10.19.0.22][6q 
yQh9EURUyO7RBC dXDow][localhost.localdomain][inet[/10.19.0.22:93 
00]](ímax local storage nodes-1, master=true}]) 
[2015-06-18 18:08:13, 208] [DEBUG] [discovery.zen.publish ] [Man 
slaughter/1003] received cluster state version 782404 
[2015-06-18 18:08:21, 803] [DEBUG] [discovery.zen.publish ] [Man 
slaughter/1003] received cluster state version 782405 
[2015-06-18 18:08:33,229] [DEBUG] [discovery.zen.publish ] [Man 
slaughter/1003] received cluster state version 782406 


日 志 中 可 以 明显 看 到 ， 节 点 是 如 何 分 别 连接 上 两 个 集群 的 。 


最 后 ， 我 们 可 以 使 用 标准 的 RESTful 接口 来 验证 一 下 : 


# curl 10.19.0.100:9201/_cat/indices?v 
health status index 

pri rep docs.count docs.deleted store.size pri.store.size 
green open test.yingjui-mweibo client downstream success-2015 


.06.07 20 1 40692459 0 154.1gb 77gb 
green open weibo-client-video-2015.06.19 

5 1 0 0 970b 575b 
green open dpool-pc-weibo-2015.06.19 

20 1 0 0 3.7kb 2.2kb 
green open logstash-video-2015.06.16 

27 © 149015413 0 13.4gb 13.4gb 


不 同 集群 的 索引 ， 都 可 以 通过 tribe node 访问 到 了 。 
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本 节 作 者 : childe 


索引 更 改名 字 时 , AEE 


用 Logstash 采 集 当 前 的 所 有 nginx 日 志 , 放 入 ES, #4] 4 H nginx-YYYY.MM.DD. 
后 来 又 增加 了 apache 日 志 , 希望 能 放 在 同一 个 索引 里 面 ,统一 叫 web-YYYYMM.DD. 


我 们 只 要 把 Logstash 配 置 更 改 一 下 ,然后 重启 , 数据 就 会 写 入 新 的 索引 名 字 下 . 但 是 
同一 天 的 索引 就 会 被 分 成 了 2 个 , kibana 上 面 就 不 好 配置 了 . 


如 此 实现 


1. 今天 是 2015.07.28. 我 们 为 nginx-2015.07.28 建 一 个 alias 叫 做 web-2015.07.28， 
之 前 的 所 有 nginx 日 志 也 如 此 照 做 . 

2. kibana 中 把 dashboard 配 置 的 索引 名 改 成 web-YYYYMM.DD 

3. 将 logstash 里 面 的 elasticsearch 的 配置 改 成 web-YYYYMM.DD, 重启 . 

4. 无 颖 切换 实现 . 


用 Logstash 采 集 当 前 的 所 有 nginx 日 志 , 放 入 ES, 索引 名 叫 nginx-YYYYMM.DD. 
某 天 (2015.07.28) 希 望 能 够 按 月 建立 索引 , 索引 名 改 成 nginx-YYYY.MM. 


[注意 ] 像 情 录 1 中 那样 新 建 一 个 叫 nginx-2015. Pur 并 指向 本 月 的 其 他 的 索引 
是 不 行 的 . 因为 一 个 alias 指 向 了 多 个 索引 , 写 这 个 alias 的 时 候 , ES 不 可 能 知道 写 入 哪 
BEA 5]. 


如 此 实现 


1. #32 ® 5| nginx-2015.07, 以 及 他 的 alias: nginx-2015.07.29, nginx-2015.07.30 
等 . #32 R 2| nginx-2015.08, 以 及 他 的 alias: nginx-2015.08.01, nginx- 
2015.08.02 ... 等 . 
2. 等 到 第 二 天 , 将 logstash 配 置 更 改 为 nginx-YYYY.MM, £ È. 
3. 如 果 索 引 只 保留 10 天 (一 般 来 说 , 不 可 能 永久 保存 ), 在 10 天 之 后 的 某 天 , 将 
kibana 配 置 更 改 为 [nginx-]YYYY.MM 


缺点 

第 二 步 ,第 三 步 需 要 记得 手工 操作 , 或 者 写 一 个 crontab 定 时 任务 . 

Fy IP FP ES 

1. 31:$ — ^- "Inginx-2015.07 alias, 并 指向 本 月 的 其 他 的 索引 . 这 个 时 候 不 能 马 
上 更 改 logstash 配 置 写 入 nginx-2015.07. 因为 一 个 alias 指 向 了 多 个 索引 , 写 这 个 


alias 的 时 候 , ES 不 可 能 知道 写 入 哪个 真正 的 索引 . 
2. 新 建 索引 nginx-2015.08, 以 及 他 的 alias: nginx-2015.08.01, nginx-2015.08.02 
3. 把 kibana 配 置 改 为 [nginx-]YYYY.MM . 
4. 到 2015.08.01 这 天 , 或 者 之 后 的 某 天 , 更 改 logstash 配 置 , 把 elasticsearch 的 配置 


更 改 为 nginx-YYYY.MM. £ È. 


缺点 


1. 7 月 份 的 索引 还 是 按 天 建立 . 
2. 第 四 步 需要 记得 导 手 工 操作 . 


情景 2 的 操作 有 些 麻烦 , 这 些 都 是 为 了 "无 颖 "这 个 大 前 提 . 我 们 不 希望 用 户 (kibana 的 
使 用 者 ) 感 觉 到 任何 变化 , 更 不 能 让 使 用 者 感受 到 数据 有 缺失 . 


如 果 用 户 愿意 妥协 , 那 ELK 的 管理 者 就 可 以 马上 简单 粗暴 的 把 数据 写 到 nginx- 
2015.07, 并 把 kibana 配 置 改过 去 . 这 样 一 来 , 用 户 可 能 就 不 能 方便 的 看 到 之 前 的 数据 
了 . 


按 域 名 配置 kibana 的 dashboard 


nginx 日 志 中 有 个 字段 是 domain, 各 个 业务 部 门 在 Kibana 中 需要 看 且 只 看 自己 域名 下 
的 日 志 . 


可 以 在 logstash 中 按 域名 切 分 索引 ,但 ES 的 metadata 会 成 倍 的 增长 , 带 来 极 大 的 负担 . 


也 可 以 放 在 nginx-YYYYMM.DD 一 个 索引 中 , 在 kibana 加 一 个 filter 过 滤 . 但 这 个 关键 
的 filter 和 其 它 所 有 filter 排 在 一 起 ,是 很 容易 很 不 小 心 清 掉 的 . 


我 们 可 以 在 template 中 配置 , 对 每 一 个 域名 做 一 个 alias. 


"aliases" : { 
"findex}-www.corp.com" : { 
aera E ea: 
"term" : { 
"domain" : "www.corp.com" 
J 
} 
tr 
"findex}-abc.corp.com" : { 
seh ld ud -3 d 
"term" : ( 
"domain" : "abc.corp.com" 
J 
} 
} 
} 


当 新 的 索引 nginx-2015.07.28 生 成 的 时 候 , 会 有 nginx-2015.07.28-www.corp.com 和 
nginx-2015.07.28-abc.corp.com 等 alias 指 向 nginx-2015.07.28. 


在 kibana 配 置 dashboard 的 时 候 , 就 可 以 直接 用 alias 做 配置 了 . 


在 实际 使 用 中 , 可 能 还 需要 一 个 crontab 定 时 的 查询 是 否 有 新 的 域名 加 入 , 自动 对 新 
域名 做 当天 的 alias, 并 把 它 加 入 template. 


映射 与 模板 的 定制 


Elasticsearch 是 一 个 schema-less 的 系统 ， 但 schema-less 并 不 代表 no 

schema > 而 是 ES 会 尽量 根据 JSON 源 数 据 的 基础 类 型 猜测 你 想 要 的 字段 类 型 映 
射 。 如 果 你 对 这 种 动态 生成 的 映射 关系 不 满意 ， 或 者 想 要 使 用 一 些 更 高 级 的 映射 设 
置 ， 那 么 就 需要 使 用 自 定义 映射 。 


创建 和 更 新 映射 


正如 上 面 所 说 ，ES 可 以 随时 根据 数据 中 的 新 字段 来 创建 新 的 映射 关系 。 所 以 ， 我 
们 也 可 以 自己 在 还 没有 正式 数据 写 入 之 前 ， 先 创建 一 个 基础 的 映射 。 等 后 续 数据 有 
其 他 字段 时 ，ES 也 一 样 会 自动 处 理 。 


映射 的 的 创建 方式 如 下 : 


# curl -XPUT http://127.0.0.1:9200/logstash-2015.06.20/_mapping 
-d' 


{ 
"mappings": { 
"syslog" : { 
"properties" : { 
"@timestamp" : { 
"type" : "date" 
3 
"message" : ( 
"type" : "text" 
ty 
EPEA g A 
"type" : "long" 
} 
} 
} 
} 


注意 : 对 于 已 存在 的 映射 ，ES 的 自动 处 理 仅 限于 新 字段 出 现 。 已 经 生成 的 字段 映 
射 ， 是 不 可 变更 的 。 如 果 确 实 需要 ， 请 参阅 之 前 的 reindex 接口 小 节 ， 采 用 重新 导 
入 数据 的 方式 完成 。 

而 如 果 是 新 增 一 个 字段 映射 的 更 新 ， 那 还 是 可 以 通过 /_mapping 接口 直接 完成 
ay: 


# curl -XPUT http://127.0.0.1:9200/logstash-2015.06.21/_mapping/ 


syslog -d ' 
{ 
"properties" : { 
"syslogtag" : ( 
"type" : "keyword", 
J 
} 
p 


没 错 ， 这 里 只 需要 单独 写 这 个 新 字段 的 内 容 就 够 了 。ES 会 自动 合并 进去 
删除 映射 


删除 数据 并 不 代表 会 删除 数据 的 映射 。 比 如 : 


# curl -XDELETE http://127.0.0.1:9200/logstash-2015.06.21/syslog 


删除 了 索引 下 syslog 的 全 部 数据 ， 但 是 syslog 的 映射 还 在 。 删 除 映射 (同时 也 就 删 
掉 了 数据 ) 的 命令 是 : 


# curl -XDELETE http://127.0.0.1:9200/logstash-2015.06.21/_mappi 
ng/syslog 


当然 ， 如 果 删 除 整 个 索引 ， 那 映射 也 是 同时 被 清除 的 。 


核心 类 型 


mapping 中 主要 就 是 针对 字段 设置 类 型 以 及 类 型 相关 参数 。 那 么 ， 我 们 首先 来 了 解 
一 下 Elasticsearch 支持 的 核心 类 型 : 


1. JSON 基础 类 型 
2. 字符 串 : text, keyword 


3. 数字 : byte, short, integer, long, float, double > half_float 
4. 时 间 : date 

5. 布尔 值 : true, false 

6. 数组 : array 

7. 对 象 : object 


8. ES 独 有 类 型 
9. 多 重 : multi 


10. 经 纬度 : geo point 

11， 网 络 地 址 ; ip 

12. 4£# xt 2: nested object 

13. 二 进 制 : binary 

14. 附件 : attachment 

前 面 提 到 ，ES 是 根据 收 到 的 ISON 数据 里 的 类 型 来 猜测 的 。 所 以 ， 一 个 内 容 为 
"123" 的 数据 ， 猜 测 出 来 的 类 型 应 该 是 字符 串 而 不 是 数值 。 除 非 这 个 字段 已 经 有 
了 确定 为 long 的 映射 关系 ， 那 么 ES 会 尝试 做 一 次 转换 。 如 果 和 转换 失败 ， 这 条 数据 

写 入 就 会 报错 。 


查看 已 有 数据 的 映射 


学 习 索 引 映射 最 直接 的 方式 ， 就 是 查看 已 有 数据 索引 的 映射 。 我 们 用 logstash S ^ 
ES 的 数据 ， 都 会 根据 logstash 自 带 的 template， 生 成 一 个 很 有 学 习 意 义 的 映射 : 


# curl -XGET http://127.0.0.1:9200/logstash-2015.06.16/_mapping/ 
tweet 


{ 
"gb": { 
"mappings": { 
"tweet": { 
"properties": { 

"date": { 
"type": "date", 
"format": "dateOptionalTime" 

3 

"name": { 
"type": "keyword" 

ty 

"tweet": { 
"type": "text" 

3 

"user id": ( 
"type": "long" 

} 

} 
} 
} 
} 
} 


目 定义 字段 映射 


大 家 可 以 通过 上 面 一 个 现存 的 映射 发 现 其 实 所 有 的 字段 都 有 好 几 个 属性 ， 这 些 都 是 
我 们 可 以 自己 定义 修改 的 。 除 了 已 经 看 到 的 这 些 基 本 内 容 外 ，ES 还 支持 其 他 一 些 
可 能 会 比较 常用 的 映射 属性 : 


e 索引 还 是 存储 
。 自 定义 分 词 器 
e 自 定义 日 期 格式 


精确 索引 


字段 都 有 几 个 基本 的 映射 选项 ， 类 型 (type)、 存 储 (store) 和 索引 方式 (index)。 默 认 
Kit > store X false 而 index X trues AA ES 会 直接 在 _source 里 存储 全 部 
JSON， 不 用 每 个 field 单独 存储 了 。 


不 过 在 非 日 志 场景 ， 比 如 用 作 监 控 存 储 的 TSDB 使 用 的 时 候 ， 我 们 就 可 以 关闭 
source ° RERA X metric 名 称 的 字段 store ; 同时 也 关闭 所 有 数值 字段 的 


index ， 只 使 用 它们 的 doc_values ° 


时 间 格 式 


稍微 见 过 Elastic Stack 示例 的 人 ， 都 对 其 中 @timestamp 字段 的 特殊 格式 有 深刻 
的 印象 。 这 个 时 间 格 式 在 Nginx 中 叫 $time iso8601 > Æ Rsyslog T"| date- 
rfc3339 > Æ ES 中 叫 date0ptionalTime 。 但 事实 上 ，ES 完全 可 以 接收 其 他 

时 间 格 式 作 为 时 间 字 段 的 内 容 。 对 于 ES 来 说 ， 时 间 字 段 内 容 实际 都 是 转换 成 long 
类 型 作为 内 部 存储 的 。 所 以 ， 接 收 段 的 时 间 格 式 ， 可 以 任意 配置 : 


"@timestamp" : { 
"type" : "date" 
"format" : "dd/MMM/YYYY:HH:mm:ss Z", 


而 ES 默认 的 时 间 字 段 格式 ， 除 了 dateoptionalTime 以 处， 还 有 一 种 ， 就 是 
epoch millis ， 毫 秒 级 的 UNIX 时 间 惟 。 因 为 这 个 数值 ES 可 以 直接 毫 不 修改 的 
存 成 内 部 实际 的 long 数值 。 此 外 ， 从 ES 2.0 开始 ， 新 增 了 对 秒 级 UNIX WY MA RAY 
支持 ， 其 format 定义 为 epoch second ° 


注意 : 从 ES 2.x 开始 ， 同 名 date 字段 的 format 也 必须 保持 一 致 。 


多重 索引 


多 重 索 引 是 logstash 用 户 最 习惯 的 一 个 映射 ， 因 为 这 是 logstash 默认 设置 开局 的 
配置 : 


"title": { 
"type" : "text", 
"fields": { 
"raw": ( "type": "keyword" } 


其 作用 是 ， 在 title 字段 数据 写 入 的 时 候 ，ES 会 自动 生成 两 个 字段 ， 分 别 是 
title 和 title.raw 。 这 样 ， 在 可 能 同时 需要 分 词 与 不 分 词 结 果 的 环境 下 ， 就 
可 以 很 灵活 的 使 用 不 同 的 索引 字段 了 。 上 比如， 查看 标题 中 最 常用 的 单词 ， 应 该 使 用 
title 字段 ; 查看 阅读 数 最 多 的 文章 标题 ， 应 该 使 用 title.raw 字段 。 


注意 : raw 这 个 名 字 你 可 以 自己 随意 取 。 比 如 说 ， 如 果 你 绝 大 多 数 时 候 用 的 是 精确 
索引 ， 那 么 你 完全 可 以 为 了 方便 反 过 来 定义 : 


ipta vr 
"type": "keyword", 
"fields": ( 


wA : 1 "type" : "text" } 


特殊 字段 


上 面 介绍 的 ， 都 是 对 普通 数据 字段 的 一 些 常 用 设置 。 而 实际 上 ，ES 默认 还 有 一 些 
特殊 字段 ， 在 软 默 的 发 挥 着 作用 。 这 些 字段 ， 统 一 以 ” 下 划 线 开头 。 在 之 前 
CRUD 章节 中 ， 我 们 就 已 经 看 到 一 些 ， 比 如 index > _type > id ° RUR 
开启 的 还 有 _parent 等 。 这 里 需要 介绍 三 个 ， 对 我 们 索引 和 检索 的 效果 和 性 能 ， 
都 有 较 大 影响 的 : 


_all 


all 里 存储 了 各 字段 的 数据 内 容 。 其 作用 是 ， 在 检索 的 时 候 ， 如 果 无 法 或 者 未 
指明 具体 搜索 哪个 字段 的 数据 ， 那 么 ES 默认 就 会 是 从 all 里 去 查找 。 


对 于 日 志 场 景 ， 如 果 你 的 日 志 划 分 出 来 的 字段 比较 少 且 数 目 国定 。 那 么 ， 完 全 可 以 
关闭 掉 _all 功能 ， 节 省 这 部 分 ID fe CPUC 


Weal : 1 
"enabled" : false 


Elastic.co 甚至 考虑 在 6.0 版 本 中 废弃 掉 all ， 由 用 户 自 定义 字段 来 完成 类 似 工 
作 ( 比 如 日 志 场 景 中 的 message 字段 )。 因为 all 采用 的 分 词 器 和 用 户 自 定 义 
字段 可 能 是 不 一 致 的 ， 某 些 场景 下 会 产生 误解 。 


_field_names 


field names 里 存储 的 是 每 条 数据 里 的 字段 名 ， 你 可 以 认为 它 是 all 的 补 
集 。 其 主要 作用 是 在 做 missing 或 exists 查询 的 时 候 ， 不 用 检索 数据 本 
身 ， 直 接 获 取 字 段 名 对 应 的 文档 ID。 听 起 来 似乎 蛮 不 错 的 ， 但 是 文档 较 多 的 时 候 ， 
就 意味 着 这 个 倒 排 链 非常 长 ! 而 且 几 乎 每 次 索引 写 入 操作 ， 都 需要 往 这 个 倒 排 里 加 
入 文档 ID， 这 点 是 实际 使 用 中 非常 损耗 写 入 性 能 的 地 方 。 


除非 有 必要 理由 ， 关 闭 field names 可 以 提升 大 概 20% 的 写 入 性 能 。 


Source 


source 里 存储 了 该 条 记录 的 JSON 源 数 据 内 容 。 这 部 分 内 容 只 是 按照 ES 接收 
到 的 内 容 原样 存储 下 来 ， 并 不 经 过 索引 过 程 。 对 于 ES 的 请 求 过 程 来 说 ， 它 不 参与 
Query 阶段 ， 而 只 用 于 Fetch 阶段 。 我 们 在 GET 或 者 /_search 时 看 到 的 数据 
内 容 ， 都 是 从 _source 里 获取 到 的 。 


所 以 ， 虽 然 _source 也 重复 了 一 遍 索 引 中 的 数据 ， 一 般 我 们 并 不 建议 关闭 这 个 功 
能 。 因 为 一 旦 关闭 ， 你 搜索 的 结果 除了 一 个 id ， 啥 都 看 不 到 。 对 于 日 志 场 景 ， 
意义 不 是 很 大 。 


当然 ， 也 有 少数 场景 是 可 以 关闭 source 的 : 


1. 把 ES 作为 时 间 序 列 数据 库 使 用 ， 只 要 聚合 统计 结果 ， 不 要 源 数 据 内容 。 
2. 把 ES 作为 纯 检 索 工 具 使 用 ， id 对 应 的 内 容 在 HDFS 上 另外 存储 ， 搜 索 后 
使 用 所 得 id 去 HDFS 上 读 取 内 容 。 


动态 模板 映射 


不 想 使 用 默认 识别 的 结果 ， 单 独 设置 一 个 字段 的 映射 的 方法 ， 上 面 已 经 介绍 完毕 。 
那么 ， 如 果 你 有 一 类 相似 的 数据 字段 ， 想 要 统一 设置 其 映射 ， 就 可 以 用 到 下 一 项 功 
能 : 动态 模板 映射 ( dynamic templates ) ° 


" default " : { 
"dynamic templates" : [ { 
"message field" : { 
"mapping" : ( 
"omit norms" : true, 
"store" : false, 
"type" : "text" 
ty 
"match" : "*msg", 
"match_mapping_type" : "string" 
} 
} {í 
"string_fields" : { 
"mapping" : { 
"ignore_above" : 256, 
"store" : false, 
"type" : "keyword" 
3 
Minatelis cor 
"match mapping type" : "string" 
} 
yl, 
"properties" : { 
} 


w 


这 样 ， 只 要 字符 串 类 型 字段 名 以 msg 结尾 的 ， 都 会 经 过 全 文 索引 ， 其 他 字符 串 字 
段 则 进行 精确 索引 。 同 理 ， 还 可 以 继续 书写 其 他 类 型 ( long , float, date 等 ) 
的 match mapping type 和 match 。 


索引 模板 


对 每 个 希望 自 定义 映射 的 索引 ， 都 要 定时 提前 通过 发 送 PUT 请 求 的 方式 创建 索引 
的 话 ， 未 免 太 过 麻烦 。ES 对 此 设计 了 索引 模板 功能 。 我 们 可 以 针对 同一 类 索引 ， 
定制 相同 的 模板 。 


模板 中 的 内 容 包括 两 大 类 ，setting( 设 置 ) 和 mapping( 映 射 )。setting 部 分 ， 多 为 在 
elasticsearch.yml 中 可 以 设置 全 局 配置 的 部 分 ， 而 mapping 部 分 ， 则 是 这 节 
之 前 介绍 的 内 容 。 


如 下 为 定义 所 有 以 te 开头 的 索引 的 模板 : 


# curl -XPUT http://localhost:9200/_template/template_1 -d ' 
{ 


"template" : "te*", 
"settings" : { 
"number_of_shards" : 1 
ty 
"mappings" : { 
"typel" - { 
" source" : { "enabled" : false } 
j 
} 


} 1 


同时 ， 索 引 模 板 是 有 序 合 并 的 。 如 果 我 们 在 同一 类 索引 里 ， 又 想 单 独 修改 某 一 小 类 
索引 的 一 两 处 单独 设置 ， 可 以 再 累加 一 层 模板 : 


# curl -XPUT http://localhost:9200/_template/template_2 -d ' 
{ 


"order" : 4, 
"template" : "tete*", 
"settings" : { 
"number_of_shards" : 2 
ty 
"mappings" : ( 
"typei" : ( 


" all" : { "enabled" : false } 


} 1 


默认 的 order 是 0， 那么 新 创建 的 order 为 1 的 template 2 在 合并 时 优先 级 大 于 
template 1。 最 终 ， 对 tete*/typei 的 索引 模板 效果 相当 于 : 


{ 
"settings" : { 
"number_of_shards" : 2 
ty 
"mappings" : { 
“type1 : { 
" source" : { "enabled" : false }, 
" all" : { "enabled" : false } 
} 
} 


Puppet 4 #284 Elasticsearch 


Elasticsearch 作为 一 个 Java 应 用 ， 本 身 的 部 署 已 经 非常 简单 了 。 不 过 作为 生产 环 
境 ， 还 是 有 必要 采用 一 些 更 标准 化 的 方式 进行 集群 的 管理 。Elasticsearch 官方 提供 
并 推荐 使 用 Puppet 方式 部 署 和 管理 。 其 Puppet 模块 源码 地 址 见 : 


https://github.com/elastic/puppet-elasticsearch 


安装 方法 


和 其 他 标准 Puppet Module 一 样 ，puppet-elasticsearch 也 可 以 通过 Puppet Forge 


ne dE 


直接 安装 : 


# puppet module install elasticsearch-elasticsearch 


配置 示例 


安装 好 Puppet 模块 后 ， 就 可 以 使 用 了 。 模 块 提供 几 种 Puppet 资源 ， 主 要 用 法 如 
下 


. 
. 


class { 'elasticsearch': 
version => '2.4.1', 
config => ( 'cluster.name' => 'es1003' }, 
java_install => true, 


j 


elasticsearch::instance ( $fqdn: 

config => ( 'node.name' => $fqdn }, 

init defaults => { 'ES USER' => 'elasticsearch', 'ES HEAP SIZE 
' => $memorysize > 64 ? '31g' : $memorysize / 2 }, 

datadir => [ '/datai/elasticsearch' ], 


} 


elasticsearch::template { 'templatename': 

host => $::ipaddress, 

port => 9200, 

content => '{"template":"*", "settings": {"number_of_replicas":0 
phr 
} 


示例 中 展示 了 三 种 资源 : 


e class: 配置 具体 安装 的 Elasticsearch 软件 版 本 ， 全 集群 公用 的 一 些 基 础 配置 
项 。 注 意 ，puppet-elasticsearch 模块 默认 并 不 负责 Java 的 安装 ， 它 只 是 调用 
操作 系统 对 应 的 Yum? Apt 工具 ， 而 elasticsearch.rpm 或 者 
elasticsearch.deb 本 身 没有 定义 其 他 依赖 (因为 java 版 本 太 多 了 ， 定 义 起 来 不 
方便 )。 所 以 ， 如 果 依 然 要 走 puppet-elasticsearch 配置 来 安装 Java 的 话 ， 需 
要 额外 开启 java install 选项 。 该 选项 会 使 用 另 一 个 Puppet Module 一 
puppetlabs-java 来 安装 ， 默 认 安 装 的 是 jdk。 如 果 你 要 节省 空间 ， 可 以 再 加 一 
^j java package 来 明确 指定 软件 全 名 。 

e instance: 配置 具体 单个 进程 实例 的 配置 。 其 中 config 和 init_defaults 
选项 在 class 和 instance 资源 中 都 可 以 定义 ， 实 际 运行 时 ， 会 自动 做 一 次 合 
并 ， 当 然 ，instance 里 的 配置 优先 级 高 于 class 中 的 配置 。 此 外 ， 最 重要 的 定 
义 是 数据 目录 的 位 置 。 有 多 快 磁盘 的 ， 可 以 在 这 里 定义 一 个 数组 。 

。 template: 模板 是 Elasticsearch 创建 索引 映射 和 设置 时 的 预定 义 方式 。 一 般 可 
以 通过 在 config/templates/ 目录 下 放置 JSON 文件 ， 或 者 通过 RESTful 
API 上 传 配 置 两 种 方式 管理 。 而 这 里 ， 单 独 提供 了 template 资源 ， 通 过 
puppet 来 管理 模板 。 content 选项 中 直接 填 入 模板 内 容 ， 或 者 使 用 file 
选项 读 取 文件 均 可 。 


事实 上 ， 模 块 还 提供 了 plugin 和 script 资源 管理 这 两 方面 的 内 容 。 考 虑 在 ELK 
中 ， 二 者 用 的 不 是 很 多 ， 本 节 就 不 单独 介绍 了 。 想 了 解 的 读者 可 以 参考 官方 文档 。 


集群 版 本 升级 


Elasticsearch 作为 一 个 新 兴 项 目 ， 版 本 更 新 非常 快 。 而 且 每 次 版 本 更 新 都 或 多 或 少 
带 有 一 些 重要 的 性 能 优化 、 稳 定性 提升 等 特性 。 可 以 说 ，ES 集群 的 版 本 升级 ， 是 
目前 ES 运 维 必 然 要 做 的 一 项 工作 。 


按照 ES 官方 设计 ， 有 restart upgrade 和 rolling upgrade 两 种 可 选 的 升级 方式 。 对 
于 1.0 版 本 以 上 的 用 户 ， 推 荐 采用 rolling upgreade 方式 。 


但 是 ， 对 于 主要 负载 是 数据 写 入 的 Elastic Stack 场景 来 说 ， 却 并 不 是 这 样 ! 
rolling upgrade 的 步骤 大 致 如 下 : 


1. 暂停 分 片 分 配 ; 
2. 单 节点 下 线 升 级 重启 ; 

3， 开 启 分 片 分 配 ; 

4. 等 待 集群 状态 变 绿 后 继续 上 述 步 骤 。 


实际 运行 中 ， 步 骤 2 的 ES 单 节点 从 restart 到 加 入 集群 ， 大 概要 100s 左右 的 时 
间 。 也 就 是 说 ， 这 100s 内 ， 该 节点 上 的 所 有 分 片 都 是 unassigned 状态 。 而 按照 
Elasticsearch 的 设计 ， 数 据 写 入 需要 至 少 达 到 replica/2+1 个 分 片 完 成 才能 算 
完成 。 也 就 意味 着 你 所 有 索引 都 必须 至 少 有 1 个 以 上 副本 分 片 开 局。 


但 事实 上 ， 很 多 日 志 场 景 ， 由 于 写 入 性 能 上 的 要 求 要 高 于 数据 可 靠 性 的 要 求 ， 大 家 
普遍 减 小 了 副本 数量 ， 甚 至 直接 关 掉 副本 复制 。 这 样 一 来 ， 整 个 rolling upgrade 期 
闻 ， 数 据 写 入 就 会 受到 严重 影响 ， 完 全 责 失 了 rolling 的 必要 性 。 

其 次 ， 步 又 3 中 的 ES 分 片 均衡 过 程 中 ， 由 于 ES 的 副本 分 片 数 据 都 需要 从 主 分 片 
走 网 络 复 制 重新 传输 一 次 ， 而 由 于 重启 ， 新 升级 的 节点 上 的 分 片 肯 定 全 是 副本 分 片 
(除非 压根 没 副 本 )。 在 数据 量 较 大 的 情况 下 ， 这 个 步骤 耗 时 可 能 是 几 十 分 钟 其 至 以 
小 时 计 。 而 且 并 发 和 限 速 上 稍微 不 注意 ， 可 能 导致 分 片 均衡 的 带宽 直接 占 满 网 卡 ， 
正常 写 入 也 还 是 受到 影响 。 

所 以 ， 对 于 写 入 压力 较 大 ， 数 据 可 靠 性 要 求 偏 低 的 实时 日 志 场 景 ， 依 然 建议 大 家 进 
行 主 动 停机 式 的 restart upgrade ° 

restart upgrade 的 步骤 如 下 : 


1. 首先 适当 加 大 集群 的 数据 恢复 和 分 片 均衡 并 发 度 以 及 磁盘 限 速 : 


# curl -XPUT http://127.0.0.1:9200/_cluster/settings -d '( 


"persistent" : ( 
"cluster" : { 
"routing" : { 

"allocation" : { 
"disable_allocation" : "false", 
"cluster_concurrent_rebalance" : "5", 
"node_concurrent_recoveries" : "5", 
"enable" : "all" 

j 

} 
tr 
"indices" : ( 
"recovery" : ( 
"concurrent streams" : "30", 
"max bytes per sec" : "2gb" 
} 
} 
ty 
"transient" : { 
"cluster" : { 
"routing" : { 
"allocation" : { 
"enable" : "all" 
} 
} 
} 
} 


# curl -XPUT http://127.0.0.1:9200/_cluster/settings -d '( 
"transient" : { 
"cluster.routing.allocation.enable" : "none" 


} 1 


1. 通过 配置 管理 工具 下 发 新 版 本 软件 包 

2. 公告 周知 后 ， 停 止 数 据 写 入 进程 ( 即 logstash indexer 等 ) 

3. 如 果 使 用 Elasticsearch 1.6 版 本 以 上 ， 可 以 手动 运行 一 次 synced flush， 同 步 
副本 分 片 的 commit id， 缩 小 恢复 时 的 网 络 传输 带宽 : 


# curl -XPOST http://127.0.0.1:9200/_flush/synced 


1. 全 集群 统一 停止 进程 ， 更 新 软件 包 ， 重 新 启动 。 
2. 等 待 各 节点 都 加 入 到 集群 以 后 ， 恢 复 分 片 分 配 : 


# curl -XPUT http://127.0.0.1:9200/_cluster/settings -d '( 
"transient" : { 
"cluster.routing.allocation.enable" : "all" 
J 
J 


由 于 同时 启 停 ， 主 分 片 几 乎 可 以 同时 本 地 恢复 ， 整 个 集群 从 red 变 成 yellow A FZ 
2 分 钟 左右 。 而 后 的 副本 分 片 ， 如 果 有 synced flush， 同 样本 地 恢复 ， 否 则 网 络 恢 
复 总 耗 时 ， 视 数据 大 小 而 定 ， 会 明显 大 于 单 节点 恢复 的 耗 时 。 


1. 如 果 有 synced flush， 建 议 等 待 集群 变 成 green 状态 后 ， 恢 复写 入 ; 否则 在 集 
群 变 成 yellow 状态 之 后 ， 即 可 着 手 开 始 恢 复数 据 写 入 进程 。 


镜像 备份 


本 节 作 者 : BRI 

大 多 数 公司 在 使 用 Elasticsearch 之 前 ， 都 已 经 维护 有 一 套 Hadoop 系统 。 因 此 ， 
在 实时 数据 慢 慢 变 得 冷却 ， 不 再 被 经 常 使 用 的 时 候 ， 一 个 需求 自然 而 然 的 就 出 现 
f : 怎么 把 Elasticsearch 索引 数据 快速 转移 到 HDFS 上 ， 以 解决 Elasticsearch 上 
的 磁盘 空间 ; 而 在 我 们 需要 的 时 候 ， 又 可 以 较 快 的 从 HDFS 上 把 索引 恢复 回来 继续 
使 用 呢 ? 

Elasticsearch 为 此 提供 了 snapshot 接口 。 通 过 这 个 接口 ， 我 们 可 以 快速 导入 导出 
索引 镜像 到 本 地 磁盘 ， 网 络 磁盘 ， 当 然 也 包括 HDFS 。 


HDFS 插件 安装 配置 
下 载 repository-hdfs 插 件 ， 通 过 标准 的 elasticsearch plugin 安装 命令 安装 : 


bin/plugin install elasticsearch/elasticsearch-repository-hdfs/2 
.2.0 


然后 在 elasticsearch.yml 中 增加 以 下 配置 : 


# repository 配置 
hdfs: 

uri: "hdfs://<host>:<port>"(Xiport wv 8020) 

#Hadoop file-system URI 

path: "some/path" 

#path with the file-system where data is stored/loaded 

conf .hdfs_config:"/hadoop/hadoop-2.5.2/etc/hadoop/hdfs-site. 
xml" 

conf .hadoop_config:"/hadoop/hadoop-2.5.2/etc/hadoop/core-sit 
e.xml" 

load defaults:"true" 

Zwhether to load the default Hadoop configuration (default) 
or not 

compress: "false" 

# optional - whether to compress the metadata or not (defaul 
t) 

chunk size:"10mb" 

# optional - chunk size (disabled by default) 
# 禁用 jsm 
security.manager.enabled: false 


默认 情况 下 ，Elasticsearch 为 了 安全 考虑 会 在 运行 JVM 的 时 候 执行 JSM。 出 于 
Hadoop 和 HDFS 客户 端 权限 问题 ， 所 以 需要 禁用 JSM。 将 
elasticsearch.yml 中 的 security.manager.enabled 设置 为 false 。 


将 插件 安装 好 ， 配 置 修改 完毕 后 ， 需 要 重启 Elasticsearch 服务 。 没 有 重启 节点 播 
件 可 能 会 执行 失败 。 


注意 : Elasticsearch 集群 的 每 个 节点 都 要 执行 以 上 步骤 |! 


Hadoop 配置 


本 节 内 容 基 于 Hadoop 版 本 : 2.5.2， 假 定 其 配置 文件 目录 : hadoop- 
2.5.2/etc/Hadoop。 注 意 ， 安 装 hadoop 集 群 需要 建立 主机 互信 ， 互 信 方 法 请 自行 查 
询 ， 很 简单 。 


相关 配置 文件 如 下 : 


mapred-site.xml.template 


RUAA mapred-site.xml 文件 ， 复 制 mapred-site.xml.template 一 份 ， 并 把 名 字 
改 为 mapred-site.xml， 需 要 修改 3 处 的 IP 为 本 机 地 址 : 


<configuration> 
<property> 
<name>mapreduce. framework .name</name> 
<value>yarn</value> 
</property> 
<property> 
<name>mapreduce. jobtracker .http.address</name> 
<value>XX.XX.XX.XX:50030</value> 
</property> 
<property> 
<name>mapreduce. jobhistory.address</name> 
«value» XX.XX.XX.XX:10020«/value» 
</property> 
<property> 
<name>mapreduce. jobhistory.webapp.address</name> 
«value» XX.XX.XX.XX:19888«/value» 
</property> 
</configuration> 


yarn-site.xml 


需要 修改 5 处 的 IP 为 本 机 地 址 : 


<configuration> 


<!-- Site specific YARN configuration properties --> 
<property> 
<name>yarn.nodemanager .aux-services</name> 
<value>mapreduce_shuffle</value> 
</property> 
<property> 
<name>yarn.resourcemanager .address</name> 
«value» XX.XX.XX.XX:8032«/value» 
</property> 
<property> 
<name>yarn.resourcemanager .scheduler.address</name> 
«value» XX.XX.XX.XX:8030«/value» 
</property> 
<property> 
<name>yarn.resourcemanager .resource-tracker .address</nam 
e> 
«value» XX.XX.XX.XX:8031«/value» 
</property> 
<property> 
<name>yarn.resourcemanager .admin.address</name> 
«value» XX.XX.XX.XX:8033«/value» 
</property> 
<property> 
<name>yarn.resourcemanager .webapp.address</name> 
«value» XX.XX.XX.XX:8088«/value» 
</property> 
</configuration> 
hadoop-env.sh 


修改 jdk X42 fe jvm 内 存 配置 ， 内 存 使 用 根据 情况 配置 。 


export JAVA HOME-/usr/java/jdki1.7.0 79 
export HADOOP PORTMAP OPTS-"-Xmx512m $HADOOP PORTMAP OPTS" 
export HADOOP CLIENT OPTS-"-Xmx512m $HADOOP CLIENT OPTS" 


core-site.xml 
临时 目录 及 hdfs 机 器 IP 端口 指定 : 


hadoop.tmp.dir /soft/hadoop-2.5.2/tmp Abase for other temporary directories. 
fs.defaultFS hdfs:// XX.XX.XX.XX:9000 io.file.buffer.size 4096 


slaves 


配置 集群 |P 地址 ， 集 群 有 几 个 IP 都 要 配置 进去 : 


192.168.0.2 
192.168.0.3 
192.168.0.4 


hdfs-site.xml 


namenode 和 datenode 数据 存放 路 径 及 别名 : 


<configuration> 
<property> 
<name>dfs.namenode.name.dir</name> 
<value>/data01/hadoop/name</value> 
</property> 
<property> 
<name>dfs.datanode.data.dir</name> 
<value>/data01/hadoop/data</value> 
</property> 
<property> 
<name>dfs.replication</name> 
<value>1</value> 
</property> 
</configuration> 


启动 Hadoop 


格式 化 完成 后 也 可 使 用 sbin/start-all.sh Ba > 142A TAE HMR o ERIR 
照 顺序 分 开启 动 。 


1. 首先 需要 格式 化 存储 : bin/Hadoop namenode -format 
2. 启动 start-dfs.sh sbin/start-dfs.sh 
3. 启动 start-yarn.sh sbin/start-yarn.sh 


curl -XPUT 'localhost:9200/ snapshot/backup' -d 
Al 
"type":"hdfs", 
"settings": { 
"path":"/test/repo", 
"uri":"hdfs://<uri>:<port>" 


} I 


在 这 步 可 能 会 报错 。 通 常 是 因为 hadoop 配置 问题 ， 更 改 好 配置 需要 重新 格式 化 文 
件 系统 : 


在 hadoop 目录 下 执行 bin/hadoop namenode -format 
索引 快照 
执行 索引 快照 命令 ， 可 写 入 crontab， 定 时 执行 


curl -XPUT 'http://localhost:9200/ snapshot/backup/snapshot 1' - 
d 
'("indices":"indices 01, indices_92"}' 
N 4A 
备份 恢复 


curl -XPOST "localhost:9200/ snapshot/backup/snapshot 1/ restore" 


备份 删除 
curl -XDELETE "localhost:9200/ snapshot/backup/snapshot 1" 
查看 仓库 信息 


curl -XGET 'http://localhost:9200/ snapshot/backup?pretty' 


rollover 


Elasticsearch 从 5.0 开始 ， 为 日 志 场 景 的 用 户 提供 了 一 个 很 不 错 的 接口 ， 叫 
rollover。 其 作用 是 : 当 某 个 别名 指向 的 实际 索引 过 大 的 时 候 ， 自 动 将 别名 指向 下 一 
个 实际 索引 。 


因为 这 个 接口 是 操作 的 别名 ， 所 以 我 们 依然 需要 首先 自己 创建 一 个 开始 滚动 的 起 始 
索引 : 


# curl -XPUT 'http://localhost:9200/logstash-2016.11.25-1' -d '( 
"aliases": { 
"logstash": {} 


}' 
然后 就 可 以 尝试 发 起 rollover 请 求 了 : 


# curl -XPOST 'http://localhost:9200/logstash/_rollover' -d '( 
"Conditions": { 
"max age": bye Eo am 
"max docs": 10000000 


T 
上 面 的 定义 意思 就 是 : 当 索 引 超过 1 天 ， 或 者 索引 内 的 数据 量 超过 一 千 万 条 的 时 
候 ， 自 动 创建 并 指向 下 一 个 索引 。 
这 时 候 有 几 种 可 能 性 : 


e 条 件 都 没 满足 ， 直 接 返 回 一 个 false， 索 引 和 别名 都 不 发 生 实际 变化 ; 


"old index" : "logstash-2016.11.25-1", 
"new index" : "logstash-2016.11.25-1", 
"rolled over" : false, 

"dry_run" : false, 

"acknowledged" : false, 
"shards_acknowledged" : false, 
"conditions" : { 


"[max_docs: 10000000]" : false, 
"[max_age: 1d]" : false 


e 还 没 满 一 天 ， 满 了 一 千 万 条 ， 那 么 下 一 个 索引 名 会 是 : logstash- 
2016.11.25-000002 ; 

e 还 没 满 一 千 万 条 ， 满 了 一 天 ， 那 么 下 一 个 索引 名 会 是 : logstash- 
2016.11.26-000002 ° 


shrink 


Elasticsearch 一 直 以 来 都 是 国定 分 片 数 的 。 这 个 策略 极 大 的 简化 了 分 布 式 系统 的 复 
杂 度 ， 但 是 在 一 些 场景 ， 比 如 存储 metric 的 TSDB、 人 小 数据 量 的 日 志 存 储 ， 人 们 会 
期 望 在 多 分 片 快 速写 入 数据 以 后 ， 把 老 数 据 合 并 存储 ， 节 约 过 多 的 cluster state 容 
È ° M 5.0 版 本 开始 ，Elasticsearch 新 提供 了 shrink 接口 ， 可 以 成 倍数 的 合并 分 片 
数 。 


注 : 所 谓 成 倍数 的 ， 就 是 原来 有 15 个 分 片 ， 可 以 合并 缩减 成 5 个 或 者 3 个 或 者 1 


整个 合并 缩减 的 操作 流程 ， 大 概 如 下 : 


. 先 把 所 有 主 分 片 都 转移 到 一 台 主机 上 ; 
. 在 这 台 主 机 上 创建 一 个 新 索引 ， 分 片 数 较 小 ， 其 他 设置 和 原 索引 一 致 ; 
. 把 原 索引 的 所 有 分 片 ， 复 制 〈 或 硬 链 接 ) 到 新 索引 的 目录 下 S 

. 对 新 索引 进行 打开 操作 恢复 分 片 数据 。 

(可 选 ) 重 新 把 新 索引 的 分 片 均衡 到 其 他 节点 上 。 


O A O N 一 


准备 工作 


e 因为 这 个 操作 流程 需要 把 所 有 分 片 台 主 机 上 ， 所 以 作为 shrink 主 
机 ， 它 的 磁盘 要 足够 大 ， 至 少 要 能 放 得 下 一 整个 索引 。 

e 最 好 是 一 整 块 磁盘 ， 因 为 硬 链接 是 不 io 。 靠 复制 太 慢 了 。 

e 开始 迁移 : 


# curl -XPUT 'http://localhost:9200/metric-2016.11.25/ setti 


ngs' -d ' 
{ 
"settings": { 
"index.routing.allocation.require. name": "shrink node 
_name", 
"index.blocks.write": true 
} 
y! 
shrink 操作 


curl -XPOST 'http://localhost:9200/metric-2016.11.25/_shrink/old 
metric-2016.11.25' -d' 


{ 

"settings": { 
"index.number_of_replicas": 1, 
"index.number_of_shards": 3 

3 

"aliases": { 

"metric-tsdb": {} 

} 

r' 


这 个 命令 执行 完 会 立刻 返回 ， 但 是 Elasticsearch 会 一 直 等 到 shrink 操作 完成 的 时 
候 ， 才 会 趴 的 开始 做 replica 分 片 的 分 配 和 重 均衡 ， 此 前 分 片 都 处 于 initializing 状 


注意 : Elasticsearch 有 一 个 硬 编 码 限 制 ， 单 个 分 片 内 的 文档 总 数 不 得 超过 
2147483519 人 个。 一般 来 说 这 个 限制 在 日 志 场 景 下 是 不 太 会 触发 的 ， 但 是 如 果 做 
TSDB 用 ， 则 需要 多 加 注意 ! 


Ingest 7 点 


Ingest 节点 是 Elasticsearch 5.0 新 增 的 节点 类 型 和 功能 。 其 开启 方式 为 : 在 
elasticsearch.yml 中 定义 : 


node.ingest: true 


d 节点 的 基础 原理 ， 是 : S RAM 据 之 后 ， 根 据 请 求 参 数 中 指定 的 管道 流 
> 找到 对 应 的 已 注册 管道 流 ， ert 处 理 ， 然 后 将 处 理 过 后 的 数据 ， 按 照 


Elasticsearch 标准 的 indexing 流程 继续 运 和 
EE oL 
创建 管道 流 


curl -XPUT http://localhost:9200/_ingest/pipeline/my-pipeline-id 
-d' 


{ 
"description" : "describe pipeline", 
"processors" : [ 
{ 
"convert" : { 
fie ane EOD 
"type": "integer" 
} 
} 
] 
了 


然后 发 送 端 带 着 这 个 my-pipeline-id 发 请 求 就 好 了 。 示 例 见 本 书 beats 章节 的 


测试 管道 流 


有 知道 自己 的 ingest 配置 是 否 正 确 ， 可 以 通过 仿 丨 接口 测试 验证 一 下 : 


curl -XPUT http://localhost:9200/_ingest/pipeline/_simulate -d ' 


{ 
"pipeline" : ( 


"description" : "describe pipeline", 
"processors" : [ 
{ 
"sert rr 
"field": "foo", 
"value": "bar" 
} 
} 
] 
ty 
doc sS 
{ 
"_index": "index", 
"_type": "type", 
E ORo o 
" source": { 
toot bar 
} 
} 
] 
r' 
Ab 3E 25 


Ingest 节点 的 处 理 器 ， 相 当 于 Logstash 的 filter 插件 。 事 实 上 其 主要 处 理 器 就 是 直 
接 移 植 了 Logstash 的 filter 代码 成 Java 版 本 。 目 前 最 重要 的 几 个 处 理 器 分 别 是 : 


convert 


"convert": { 
"field" : "foo", 
"type": "integer" 


} 
} 
grok 
{ 
"grok": { 
"field": "message", 
"patterns": ["my %{FAVORITE_DOG:dog} is colored %{RG 
B:color}"] 
"pattern definitions" : { 
"FAVORITE DOG" : "beagle", 
"RGB" : "RED|GREEN | BLUE" 
} 
} 
} 
gsub 
{ 
"gsub": { 
"field": "field1", 
Hesse rme. e 
"replacement": "-" 
} 
} 


date 


"date" : { 
"field" : "initial date", 
"target field" : "timestamp", 
"formats" : ["dd/MM/yyyy hh:mm:ss"], 
"timezone" : "Europe/Amsterdam" 

} 

} 
其 他 处 理 器 插件 


除了 内 置 的 处 理 器 之 外 ， 还 有 3 个 处 理 器 ， 官 方 选择 了 以 插件 性 质 单独 发 布 ， 它 们 
是 attachement > geoip 和 user-agent 。 原 因应 该 是 这 3 个 处 理 器 需要 额外 数据 模 
块 ， 而 且 处 理性 能 一 般 ， 担 心 拖累 ES 集群 。 


它们 可 以 和 其 他 普通 ES 插件 一 样 安装 : 


sudo bin/elasticsearch-plugin install ingest-geoip 


使 用 方式 和 其 他 处 理 器 一 样 : 


curl -XPUT http://localhost:9200/_ingest/pipeline/my-pipeline-id 
-2-d' 


{ 
"description" : "Add geoip info", 
"processors" : [ 
t 
"geoip" : { 
UP Lelidi m ipae 
"target field" : "geo", 
"database file" : "GeoLite2-Country.mmdb.gz" 
} 
} 


Ingest 节 点 
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spark streaming 交互 


Apache Spark 是 一 个 高 性 能 集群 计算 框架 ， 其 中 Spark Streaming 作为 实时 批 处 
理 组 件 ， 因 为 其 简单 多 上 手 的 特性 深 受 喜爱 。 在 es-hadoop 2.1.0 版 本 之 后 ， 也 新 
增 了 对 Spark 的 支持 ， 使 得 结合 ES 和 Spark 成 为 可 能 。 


目前 最 新 版 本 的 es-hadoop 是 2.1.0-Beta4。 安 装 如 下 : 


wget http://d3kbcqa49mibi3.cloudfront.net/spark-1.0.2-bin-cdh4.t 
gz 

wget http://download.elasticsearch.org/hadoop/elasticsearch-hado 
op-2.1.0.Beta4.zip 


然后 通过 ADD_JARS=../elasticsearch-hadoop- 
2.1.0.Beta4/dist/elasticsearch-spark 2.10-2.1.0.Beta4.jar 环境 变量 ， 
把 对 应 的 jar 包 加 入 Spark 的 jar 环境 中 。 


下 面 是 一 段 使 用 spark streaming 接收 kafka 消息 队列 ， 然 后 写 入 ES 的 配置 : 


import org.apache.spark._ 

import org.apache.spark.streaming.kafka.KafkaUtils 
import org.apache.spark.streaming. 

import org.apache.spark.streaming.StreamingContext. 
import org.apache.spark.SparkContext 

import org.apache.spark.SparkContext._ 

import org.apache.spark.SparkConf 

import org.apache.spark.sql._ 
import org.elasticsearch.spark.sql._ 

import org.apache.spark.storage.StorageLevel 
import org.apache.spark.Logging 

import org.apache.log4j.{Level, Logger} 


object Elastic { 
def main(args: Array[String]) { 
val numThreads = 1 
val zookeeperQuorum = "localhost:2181" 
val groupId = "test" 


val topic = Array("test").map((_, numThreads) ).toMap 
val elasticResource = "apps/blog" 


val sc = new SparkConf() 
.setMaster("local[*]") 
.setAppName("Elastic Search Indexer App") 


sc.set("es.index.auto.create", "true") 
val ssc - new StreamingContext(sc, Seconds(10)) 
ssc.checkpoint ("checkpoint") 
val logs - KafkaUtils.createStream(ssc, 
zookeeperQuorum, 
groupId, 
topic, 
StorageLevel.MEMORY AND D 
ISK SER) 
.map( . 2) 


logs.foreachRDD { rdd => 
val sc = rdd.context 
val sqlContext = new SQLContext(sc) 
val log = sqlContext.jsonRDD(rdd) 
log.saveToEs(elasticResource) 


ssc.start() 
ssc.awaitTermination() 


注意 ， 代 码 中 使 用 了 spark SQL 提供 的 jsonRDD() 方法 ， 如 果 在 对 应 的 kafka 
topic 里 的 数据 ， 本 身 并 不 是 已 经 处 理 好 了 的 JSON 数据 的 话 ， 这 里 还 需要 自己 写 
一 写 额 外 的 处 理 函 数 ， 利 用 cast class 来 规范 数据 。 


Shield 权限 管理 


本 节 作 者 : cameluo 
Shield 是 Elastic 公司 官方 发 布 的 权限 管理 产品 。 其 主要 特性 包括 : 


e 提供 集群 节点 身份 验证 和 集群 数据 访问 身份 验证 
e 提供 基于 身份 角色 的 细 粒 度 资 源 和 行为 访问 控制 ， 细 到 索引 级 别 的 读 写 控制 
o 提供 节点 间 数 据 传输 通道 加 密 保 护 输出 传输 安全 

e 提供 审计 功能 

e 以 插件 的 形式 发 布 


License @ #2 R% 


Shield 是 一 款 商 业 产 品 ， 不 过 提供 30 天 免费 试用 ， 试 用 期 间 是 全 功能 的 。 过 期 后 
集群 会 不 再 正常 工作 。 


Shield 47 
用 户 认 证 : 


Shield 通过 定义 一 套用 户 集合 来 认证 用 户 ， 采 用 抽象 的 域 方 式 定义 用 户 集 合 ， 支 持 
本 地 用 户 (esusers 域 ) 和 LDAP 用 户 ( 含 AD)» 


e Shield 提供 工具 ./bin/shield/esusers 用 于 创建 和 管理 本 地 用 户 。 
e 集成 LDAP 认证 支持 映射 LDAP 安全 组 到 Shield 角色 ，LDAP 安全 组 与 
Shield 角色 可 以 是 多 对 多 的 关系 。 


Shield 支持 定义 多 个 认证 域 ， 采 用 order 字 段 进 行 优 先 级 排序 。 如 一 个 本 地 域 
esusers ，order=1， 加 一 个 LDAP 域 ，order=2。 如 果 用 户 不 再 本 地 用 户 域 中 则 在 
LDAP 域 中 查找 验证 。 


e ./config/shield/roles.yml 文件 中 定义 角色 和 角色 的 所 拥有 的 权限 。 
e ./config/shield/group_to_role_mapping.yml 文件 中 定义 LDAP 组 到 角 
色 映 射 关系 。 


节点 认证 与 通道 加 密 : 


使 用 SSL/TLS 证 书 进 行 相互 认证 和 通讯 加 密 。 加 密 是 可 选 配 置 。 如 果 不 使 用 ， 
shield 节点 之 间 可 以 进行 简单 的 密码 验证 (明文 传输 ) 。 


Shield 采用 RBAC 授权 模型 ， 数 据 模型 包含 如 下 元 素 : 


e 受 保 护 资源 (Secured Resource) : 控制 用 户 访问 的 客体 ， 包 括 cluster ` 
index/alias 等 等 。 

e 权能 (Priviliege) : 用 户 可 以 对 受 保护 资源 执行 的 一 种 或 多 种 操作 ， 如 read, 

Write 等 。 

许可 (Permissions) : 对 被 保护 的 资源 拥有 的 一 个 或 多 个 权能 ， 如 read on the 

"products" index ° 

角色 (Role) : 命名 的 一 组 许可 。 

e 用 户 (Users) : 用 户 实体 ， 可 以 被 赋予 0 个 或 多 种 角色 ， 授 权 他 们 对 被 保护 的 资 
源 执行 各 种 权能 。 


Sues 
增加 认证 尝试、 授权 失败 等 安全 相关 事件 和 活动 日 志 。 


A+ 
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1. 安装 License 和 Shield 插件 


bin/plugin -i elasticsearch/license/latest 
bin/plugin -i elasticsearch/shield/latest 


注意 : 初次 运行 Shield 需要 重新 启动 ES 集群 。 后 续 更 新 License(license.json 为 
License 文件 ) 就 可 以 在 线 运 行 : 


# curl -XPUT -u admin 'http://127.0.0.1:9200/_licenses' -d @lice 
nse.json 


1. 创建 本 地 管理 员 : 


./bin/shield/esusers useradd esadmin -r admin 


配置 


这 里 使 用 简单 的 配置 先 完成 基本 验证 : 使 用 纯 本 地 用 户 认证 或 者 使 用 本 地 认证 + 基 
本 的 ldap 认证 。 


ES 配置 


在 elasticsearch.yml 中 增加 如 下 配置 : 


hostname_verification: false 
#shield.ssl.keystore.path: /app/elasticsearch/node01. jk 
S 
Zshield.ssl.keystore.password: XXXXXX 
shield: 
authc: 
realms: 
default: 
type: esusers 
order: 1 
ldaprealm: 
type: ldap 
order: 2 
url: "ldap://ldap.example.com:389" 
bind dn: "uid-ldapuser, ou=users, o-services, dc=example 
, dc=com" 
bind password: changeme 
user search: 
base dn: "dc=example, dc=com" 
attribute: uid 
group search: 
base dn: "dc=example, dc=com" 
files: 
role mapping: "/app/elasticsearch/shield/group to role 
 mapping.yml" 
unmapped groups as roles: false 


角色 配置 


根据 默认 配置 文件 增 减 角色 和 访问 控制 权限 。 角 色 配 置 文件 可 以 在 线 修 改 ， 保 存 后 
立即 生效 : 
([INFO ][shield.authz.store ] [Winky Man] updated roles (roles file 
[/opt/elasticsearch/config/shield/roles.yml] changed)) 
注意 : 如 果 需 要 集成 kibana 认 证 ， 用 户 角 色 也 需要 有 访问 '.kibana' 索 引 的 访问 权限 
和 cluster:monitor/nodes/info 的 访问 权限 ， 上 有 具体 参照 kibana4 角 色 中 的 定义 ， 否 则 用 
户 通 过 kibana 认 证 后 仍然 无 法 访问 到 数据 索引 


用 户 组 与 角色 映射 配置 


根据 默认 配置 文件 增 减 用 户 、 用 户 组 与 角色 配置 中 定义 角色 的 映射 关系 ， 可 以 灵活 
实现 各 种 需求 。LDAP 组 仅 支持 安全 组 ， 不 支持 动态 组 。 这 个 配置 文件 可 以 在 线 修 
改 ， 保 存 后 立即 生效 : 

([INFO ][shield.authc.Idap.support] [Vishanti] role mappings file 


[/opt/elasticsearch/config/shield/group to role mapping.yml] changed for 
realm [Idap/Idaprealm]. updating mappings...) 


测试 


curl -u username http://127.0.0.1:9200/ 


searchguard 在 Elasticsearch 2.x 上 的 运用 


本 节 作 者 : wdh 
本 节 内 容 基 于 以 下 软件 版 本 : 


e elasticsearch 2.1.1-1 
e kibana 4.3.1 
e logstash 2.1.1-1 


searchguard 2.x 更 新 后 跟 shield 配置 上 很 相似 ， 相 比 之 前 的 版 本 简洁 很 多 。 
searchguard 优点 有 : 


e 节点 之 问 通过 SSL/TLS 传输 

e 支持 JDK SSL fe Open SSL 

e 支持 热 载 入 ， 不 需要 重启 服务 

e 支持 kibana4 及 logstash 的 配置 

e 可 以 控制 不 同 的 用 户 访问 不 同 的 权限 
e 配置 简单 


EE 


ES 


5 


1. 安装 search-guard-ss| 


bin/plugin install com.floragunn/search-guard-ssl/2.1.1.5 


1. 安装 search-guard-2 


bin/plugin install com.floragunn/search-guard-2/2.1.1.0-alpha2 


1. 配置 elasticsearch 支持 ssl 


elasticsearch.yml 增 加 以 下 配置 : 


Search-Guard 在 Elasticsearch 2.x 上 的 运用 


THEHHIHHHHHBBHEHHHHH HB HH HB RE 
# SEARCH GUARD SSL 


# Configuration 

# 
THER HEU EUR EH EH E HR HERR HE HH HEB EEG HH THREE EH EH TH HH E HHHHRE 
VAR UE EE ER EU E HERR E 


ZThis will likely change with Elasticsearch 2.2, see [PR 14108]( 
https://github.com/elastic/elasticsearch/pull/14108) 
security.manager.enabled: false 


Fe EEE UU S EH HU ELI HH ERE LH HL HE EHE HU HT EHE 
VAR EUR HLUHHHEHEE ERE EH HB E 
# Transport layer SSL 


# 
THEHEIHHHHHHHHH AHHH HH B THER EH HH HHHHH HH HH HH HHH E HH HH BHEHHH HH 
THHHHHHHHHHBHHHBHHHHHHBRHHBHNH BE 


# Enable or disable node-to-node ssl encryption (default: true) 

Zsearchguard.ssl.transport.enabled: false 

4 JKS or PKCS12 (default: JKS) 

Zsearchguard.ssl.transport.keystore type: PKCS12 

# Relative path to the keystore file (mandatory, this stores the 
server certificates), must be placed under the config/ dir 
searchguard.ssl.transport.keystore filepath: nodeO-keystore.jks 

4 Alias name (default: first alias which could be found) 
searchguard.ssl.transport.keystore alias: my alias 

# Keystore password (default: changeit) 
searchguard.ssl.transport.keystore password: changeit 


4 JKS or PKCS12 (default: JKS) 
Zsearchguard.ssl.transport.truststore type: PKCS12 

X Relative path to the truststore file (mandatory, this stores t 
he client/root certificates), must be placed under the config/ d 
ir 

searchguard.ssl.transport.truststore_filepath: truststore.jks 

# Alias name (default: first alias which could be found) 
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searchguard.ssl.transport.truststore_alias: my_alias 

# Truststore password (default: changeit) 
searchguard.ssl.transport.truststore_password: changeit 

# Enforce hostname verification (default: true) 
#searchguard.ssl.transport.enforce_hostname_verification: true 
# If hostname verification specify if hostname should be resolve 
d (default: true) 

#searchguard.ssl.transport.resolve_hostname: true 

# Use native Open SSL instead of JDK SSL if available (default: 
true) 

#searchguard.ssl.transport.enable_openssl_if_available: false 


THHUHHHHHHHHBHHHHHHHHIHHHHHHHHBHHEHHR HBHF HB HH AERA AAA 
THHBHHHHHBIHHBHHHHBHHHHHHBRHH BIB N BG 
4 HTTP/REST layer SSL 


# 
RRS Ee EE Re 
PoP eee eee R ee aa eae 
# Enable or disable rest layer security - https, (default: false) 


#searchguard.ssl.http.enabled: true 

# JKS or PKCS12 (default: JKS) 
#searchguard.ssl.http.keystore_type: PKCS12 

# Relative path to the keystore file (this stores the server cer 
tificates), must be placed under the config/ dir 
#searchguard.ssl.http.keystore_filepath: keystore_https_node1.jks 


# Alias name (default: first alias which could be found) 
#searchguard.ssl.http.keystore_alias: my_alias 

# Keystore password (default: changeit) 
#searchguard.ssl.http.keystore_password: changeit 

# Do the clients (typically the browser or the proxy) have to au 
thenticate themself to the http server, default is false 
#searchguard.ssl.http.enforce_clientauth: false 

# JKS or PKCS12 (default: JKS) 
#searchguard.ssl.http.truststore_type: PKCS12 

# Relative path to the truststore file (this stores the client c 
ertificates), must be placed under the config/ dir 
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#searchguard.ssl.http.truststore_filepath: truststore_https.jks 
# Alias name (default: first alias which could be found) 
#searchguard.ssl.http.truststore_alias: my_alias 

# Truststore password (default: changeit) 
#searchguard.ssl.http.truststore_password: changeit 

# Use native Open SSL instead of JDK SSL if available (default: 
true) 

#searchguard.ssl.http.enable_openssl_if_available: false 


[| 
1. 增加 searchguard 的 管理 员 帐 号 配置 ， 同 样 在 elasticsearch.yml 中 ， 增 加 以 下 
配置 : 


security.manager.enabled: false 
searchguard.authcz.admin_dn: 

- "CN-admin,OU-client,O-client,l-tEst,C-De" #DN 
1. € & elasticsearch 


将 node 证 书 和 根 证 书 放 在 elasticsearch 配置 文件 目录 下 ， 证 书 可 用 openssl + 
成 ， 修 改 了 下 官方 提供 的 脚本 。 


注意 :证 书 中 的 client 的 DN 及 server 的 oid， 证 书 不 正确 会 导致 es 服务 起 不 
ko (我 曾经 用 ejbca 生成 证 书 不 能 使 用 ) 


配置 


searchguard 主要 有 5 个 配置 文件 在 plugins/search-guard-2/sgconfig F: 
1. sg config.yml: 

主 配置 文件 不 需要 做 改动 
1. sg internal users.yml: 


user X ft > CLAP » XT ELK 我 们 需要 一 个 kibana 登录 用 户 和 一 个 logstash 
AP: 


kibana4: 
hash: $2a$12$xZOcnwYPYQ3zIadn1QIJOeNhXingwMkTN. oMwkKxoGvDVPn4/6 


Xto 
#password is: kirk 
roles: 
- kibana4 


logstash: 
hash: $2a$12$xZOcnwYPYQ3zIadn1QIJOeNhXingwMkTN. oMwkKxoGvDVPn4/6 


Xto 
OOOO ëO 
#8 £3 = Jf] plugins/search-guard-2/tools/hash.sh Æ 5X, 


1. sg_roles.yml: 

权限 配置 文件 ， 这 里 提供 kibana4 和 logstash 的 权限 ， 以 下 是 我 修改 后 的 内 容 ， 可 
自行 修改 该 部 分 内 容 (插件 安装 自 带 的 配置 文件 中 权限 不 够 ，kibana 会 登录 不 了 ， 
shield 中 同样 的 权限 却 是 够 了 ) 


sg kibana4: 
cluster: 
- cluster:monitor/nodes/info 
- cluster:monitor/health 
indices: 


* ga 


ox unes 


- indices:admin/mappings/fields/get 
- indices:admin/validate/query 
- indices:data/read/search 
- indices:data/read/msearch 
- indices:admin/get 
- indices:data/read/field stats 
'?kibana': 
LIN 
- indices:admin/exists 
- indices:admin/mapping/put 
- indices:admin/mappings/fields/get 
- indices:admin/refresh 
- indices:admin/validate/query 
- indices:data/read/get 
sg_logstash: 
cluster: 
- indices:admin/template/get 
- indices:admin/template/put 
indices: 
' logstash-*': 
a 
- WRITE 
- indices:data/write/bulk 
- indices:data/write/delete 
- indices:data/write/update 
- indices:data/read/search 
- indices:data/read/scroll 
- CREATE_INDEX 


1. sg roles mapping.yml: 


定义 用 户 的 映射 关系 ， 添 加 kibana  logstash 用 户 对 应 的 映射 : 


sg_logstash: 
users: 
- logstash 
sg_kibana4: 
backendroles: 
- kibana 
users: 
- kibana4 


1. sg action groups.yml: 


定义 权限 
加 载 配置 并 局 用 


plugins/search-guard-2/tools/sgadmin.sh -cd plugins/search-guard 
-2/sgconfig/ -ks plugins/search-guard-2/sgconfig/admin-keystore. 
jks -ts plugins/search-guard-2/sgconfig/truststore.jks  -nhnv 


(如 修改 了 密码 ， 则 需要 使 用 plugins/search-guard-2/tools/sgadmin.sh -h 查 看 对 应 
参数 ) 


注意 证 书 路 径 ， 将 生成 的 admin 证 书 和 根 证 书 放 在 sgconfig 目 录 下 。 
最 后 ， 可 以 尝试 登录 啦 | 

登录 界面 会 有 验证 

帐号 : kibana4 密码 : kirk 

更 多 的 权限 配置 可 以 自己 研究 。 

请 参考 


https://github.com/floragunncom/search-guard/tree/2.1.1 


k Jre ae ee 
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Elasticsearch 作为 一 个 分 布 式 系统 ， 监 控 自 然 是 重 中 之 重 。Elasticsearch AF 7 
供 了 非常 完善 的 ， 由 浅 及 深 的 各 种 性 能 数据 接口 。 和 数据 读 写 检索 接口 一 样 ， 采 用 
RESTful 风格 。 我 们 可 以 直接 使 用 curl 来 获取 数据 ， 编 写 监控 程序 ， 也 可 以 使 用 一 
些 现成 的 监控 方案 。 通 常 这 些 方案 也 是 通过 接口 读 取 数据 ， 解 析 ISON? eR 
面 o 


本 章 会 先 介绍 一 些 常 用 的 监控 接口 ， 以 及 其 响应 数据 的 含义 。 然 后 再 介绍 几 种 常用 
的 开源 和 商业 Elasticsearch 监控 产品 。 


集群 健康 状态 监控 


Elasticsearch 集群 监控 ， 首 先 我 们 肯定 是 需要 一 个 从 总 体 意 义 上 的 概要 。 不 
多 大 规模 的 集群 ， 告 诉 我 正常 还 是 不 正常 ? 没 错 ， 集 群 健康 状态 接口 就 是 用 来 


说 总 到 
管 是 


回答 这 


v 


> 


文 个 问题 的 ， 而 且 这 个 接口 的 信息 已 经 出 于 意料 的 丰富 了 。 


P m Bl 


# curl -XGET 127.0.0.1:9200/ cluster/health?pretty 


~ 


"cluster_name" : "es1003", 

"status" : "green", 

"timed_out" : false, 

"number_of_nodes" : 38, 
"number_of_data_nodes" : 27, 
"active_primary_shards" : 1332, 
"active_shards" : 2381, 

"relocating shards" : 0, 

"initializing shards" : 0, 

"unassigned shards" : 0, 
"number of pending tasks" : 0 

"delayed unassigned shards" : 0, 
"number of in flight fetch" : 0, 

"task max waiting in queue millis" : 0, 
"active shards percent as number" : 100.0 


KAS 3 A 


输出 


里 最 重要 的 就 是 status 这 行 。 很 多 开源 的 ES 监控 脚本 ， 


做 报警 判断 。status 有 三 个 可 能 的 值 : 


° d FUR UAE HUNE ee ， 但 是 有 副本 分 片 缺 失 。 


green 绿灯 ， 所 有 分 片 都 正确 运行 ， 集 群 非常 健康 。 


其 实 就 是 


这 种 情况 意 


拿 这 


了 数据 


意味 着 


ES 当前 还 是 正常 运行 的 ， 但 是 有 一 定 风 险 。 注 意 ， 在 Kibana4 server 端 局 


rer 0 
成 绿灯 后 才能 继续 运行 。 

e red 红 灯 ， a 部 分 数据 完全 不 可 用 。 而 考虑 到 ES 在 写 入 端 是 
简单 的 取 余 算法 ， 轮 到 这 个 分 片上 的 数据 也 会 持续 写 入 报错 。 


对 Nagios 熟悉 的 读者 ， 可 以 直接 将 这 个 红 黄 绿灯 对 应 上 Nagios 体系 中 的 
Critical > Warning * OK œ 


其 他 数据 解释 


e number_of_nodes 集群 内 的 总 节点 数 。 

e number_of_data_nodes 集群 内 的 总 数据 节点 数 。 

e active primary shards 集群 内 所 有 索引 的 主 分 片 总 数 。 

e active shards 集群 内 所 有 索引 的 分 片 总 数 。 

e relocating shards 正在 迁移 中 的 分 片 数 。 

e initializing_shards 正在 初始 化 的 分 片 数 。 

e unassigned shards 未 分 配 到 具体 节点 上 的 分 片 数 。 

e delayed unassigned shards 延 时 待 分 配 到 具体 节点 上 的 分 片 数 。 


va di TROUT f ARAB Re Oo (rete Ri WRT KAGE O 的 
情况 ， 怎 么 才能 知道 这 些 长 期 unassign initialize 的 分 片 影 响 的 是 哪个 索引 
CRAMER SiO RAKE 过 在 集群 健康 这 层 ， 本 身 就 可 以 得 
到 更 详细 一 点 的 内 容 了 。 


level 请 求 参 数 


接口 请 求 的 时 候 ， 可 以 附加 一 个 level 参数 ， 指 定 输出 信息 以 indices 还 是 shards 
级 别 显示 。 当 然 ， 一 般 来 说 ，indices 级 别 就 够 了 。 


# curl -XGET http://127.0.0.1:9200/_cluster/health?level=indices 
{ 

"cluster_name": "es1003", 

"status" red] 

"timed_out": false, 

"number_of_nodes": 38, 

"number_of_data_nodes": 27, 

"active_primary_shards": 1332, 


"active_shards": 2380, 
"relocating shards": 0, 
"initializing shards": 0, 
"unassigned_shards": 1 


"delayed_unassigned_shards" : 0, 
"number of in flight fetch" : 60, 

"task max waiting in queue millis" : 0, 
"active shards percent as number" : 99.0 


"indices": { 

"logstash-2015.05.31": ( 
"Status": "green", 
"number of shards": 81, 
"number of replicas": 0, 
"active primary shards": 81, 
"active shards": 81, 
"relocating shards": 0, 
"initializing shards": 0, 
"unassigned shards": 0 

ty 

"logstash-2015.05.30": { 
status eee, 
"number_of_shards": 81, 
"number_of_replicas": 0, 
"active_primary_shards": 80, 
"active_shards": 80, 
"relocating shards": 0, 
"initializing shards": 0, 
"unassigned_shards": 1 


ty 


这 就 看 到 了 ， 是 logstash-2015.05.30 索引 里 ， 有 一 个 分 片 一 直 未 能 成 功 分 配 ， 导 
致 集群 状态 异常 的 。 

不 过 ， 一 般 来 说 ， 集 群 健康 接口 ， 还 是 只 用 来 简单 监控 一 下 集群 状态 是 否 正常 。 一 
旦 收 到 异常 报警 ， 具 体 确 定 unassign shard 的 情况 ， 更 推荐 使 用 kopf 工具 在 页 面 
查看 。 
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ANANN 点 状态 mw» 监控 接 d 


集群 状态 是 从 最 上 层 PUE Inm ER MU 而 节点 状态 则 更 底层 一 些 ， 会 返回 
给 你 集群 里 每 个 节点 的 统计 信息 。 这 个 接口 的 信息 极为 丰富 ， 从 硬件 到 数据 到 线 
程 ， 应 有 尽 有 。 本 节 会 以 单 节点 为 例 ， 分 段 介绍 各 部 分 数据 的 含义 。 


首先 ， 通 过 如 下 命令 获取 节点 状态 : 


# curl -XGET 127.0.0.1:9200/_nodes/stats 


+e 
节 点 概要 
返回 数据 的 第 一 部 分 是 节点 概要 ， 主 要 就 是 节点 外 Ppa > 网卡 地 址 和 监听 端口 
等 。 这 部 分 内 容 除 了 极 少 数 时 候 ( 一 个 主机 上 运行 了 多 个 ES 节点 ) 一 般 没有 太 大 用 
{ 
"cluster_name": "elasticsearch zach", 
"nodes": { 


"UNr6ZMF5Qk-YCPA_L18B0Q": { 
"timestamp": 1477886018477, 
"name": "Zach", 
"transport_address": "192.168.1.131:9300", 
"ose = O22 160011313. 
"ip": "192.168.1.131:9300", 
"roles": [ 
"master", 
"data", 
"ingest" 


]; 


索引 信息 


这 部 分 内 容 会 列 出 该 节点 上 存储 的 所 有 索引 数据 的 状态 统计 。 


1. BARR : 


"indices": { 


docs or 
"count": 6163666, 
"deleted": 0 

ty 

"store": { 


"size in bytes": 2301398179, 
"throttle time in millis": 122850 
is 


docs.count 是 节点 上 存储 的 数据 条 目 总 数 ; store.size in bytes 是 节点 上 存储 的 数 
据 占 用 磁盘 的 实际 大 小 。 而 store.throttle_time_in_millis 则 是 ES 进程 在 做 
segment merge 时 出 现 磁盘 限 速 的 时 长 。 如 果 你 在 ES 的 日 志 里 经 常会 看 到 限 速 声 
明 ， 那 么 这 里 的 数值 也 会 偏 大 。 


1. BAMA: 


"indexing": 1 
"index total": 803441, 
"index time in millis": 367654, 
"index current": 99, 
"delete total": 0, 
"delete time in millis": 0, 
"delete current": 0 
"noop update total" : 0, 
"is throttled" : false, 
"throttle time in millis" : 0 


ty 


indexing.index_total 是 一 个 递增 累计 数 ， 表 示 节 点 完成 的 数据 写 入 总 次 数 。 至 于 后 
面 又 删除 了 多 少 ， 额 外 记录 在 indexing.delete total 里 ; indexing.is_throttled 是 
2.0 版 之 后 新 增 的 计数 ， 因 为 Elasticsearch 从 此 开始 自动 管理 throttle， 所 以 有 了 
这 个 计数 。 


1. 读 取 性 能 : 


"get": { 
totalt <6, 
"time_in_millis": 2, 
"exists_total": 5, 
"exists_time_in_millis": 2, 
"missing_total": 1, 
"missing_time_in_millis": 0, 
"current": 0 


ty 


get 这 里 显示 的 是 直接 使 用 id 读 取 数据 的 状态 。 


1. 搜索 性 能 : 


"search": { 

"open contexts": 0, 

"query total": 123, 
"query time in millis": 531, 
"query current": 0, 
"fetch_total": 3, 
"fetch_time_in_millis": 55, 
"fetch current": 0 
"scroll_total" : ©, 


"scroll_time_in_millis" : 0， 
"scroll_current" : 0, 
"suggest total" : 0, 
"suggest time in millis" : 0, 
"suggest current" : 0 


ty 


search.open contexts 表示 当前 正在 进行 的 搜索 ， 而 search.query_total 表示 节点 

启动 以 来 完成 过 的 总 搜索 数 ，search.query time in millis 表示 RA LE RAI 

jr AY lal a) Ae o PR’ query time in millis/query total A > ŽAR K 
能 越 差 ， 可 以 通过 ES 的 slowlog， 获 取 具 体 的 搜索 语句 ， 做 出 针对 性 的 优化 。 


search.fetch total 等 指标 含义 类 似 。 因 为 ES 的 搜索 默认 是 query-then-fetch X 
的 ， 所 以 fetch 一 般 是 少 而 快 的 。 如 果 计 算出 来 search.fetch_time_in_millis 
> search.query time in millis ， 说 明 有 人 采用 了 较 大 的 size 参数 做 分 页 查 


i9 > i$ xt. slowlog 抓 到 具体 的 语句 ， 相 机 优化 成 Scan 式 的 搜索 。 


1. 段 合 并 性 能 


"merges": { 
"current": 0, 
"current docs": 0, 
"current size in bytes": 0, 
"total": 1128, 
"total_time_in_millis": 21338523, 
"total_docs": 7241313, 
"total_size_in_bytes": 5724869463 
"total_stopped_time_in_millis" : 0, 
"total throttled time in millis" : 0, 
"total auto throttle in bytes" : 104857600 
ty 


merges 数据 分 为 两 部 分 ，current 开头 的 是 当前 正在 发 生 的 段 合并 行为 统计 ; total 
开头 的 是 历史 总 计数 。 一 般 来 说 ， 作 为 Elastic Stack 应 用 ， 都 是 以 数据 写 入 压力 为 
主 的 ，merges 相关 数据 会 比较 突出 。 


T 过 滤器 缓存 : 


"query_cache": { 
"memory size in bytes": 48, 


"total_count" : 0, 
"hit_count" : O, 

"miss_count" : 0, 
"cache size" : 0, 
"cache count" : 0, 


"evictions": 0 


ty 


query cache.memory size in bytes 表示 过 滤器 缓存 使 用 的 内 

Æ * query_cache.evictions 表示 因 内 存 满 被 回收 的 缓存 大 小 ， 这 个 数 如 果 较 大 ， 说 
明 你 的 过 滤器 缓存 大 小 不 足 ， 或 者 过 滤器 本 身 不 太 适 合 缓存 。 比 如 在 Elastic Stack 
态 景 中 常用 的 时 间 过 滤器 ， 如 果 使 用 @timestamp:["now-1d" TO "now"] 这 种 


表达 式 的 话 ， 需 要 每 次 计算 now 值 ， 就 没 法 长 期 缓存 。 事 实 上 ，Kibana 中 通过 
timepicker 生成 的 filtered 请 求 里 ， 对 @timestamp 部 分 就 并 不 是 直接 使 用 
"now" ， 而 是 在 浏览 器 上 计算 成 毫秒 数值 ， 再 发 送 给 ES 的 。 


请 注意 ， 过 滤器 缓存 是 建立 在 segment 基础 上 的 ， 在 当天 新 日 志 的 索引 中 ， 存 在 大 
量 的 或 多 或 少 的 segments。 一 个 已 经 5GB 大 小 的 s ， 和 一 个 刚刚 2MB X 
小 的 i ' 发 生 一 次 query cache. ids 对 搜索 性 能 的 影响 区 别 是 巨大 
的 。 但 是 节点 状态 中 本 身 这 个 计数 并 不 能 这 点 区 别 。 ies 以 ， 尽 力 减 少 这 个 数 
ia eee 觉 不 慢 ， 那 么 sven o 


1. id 缓存 : 
"id_cache": { 


"memory_size_in_bytes": 0 


}, 
id cache 是 parent/child mappings 使 用 的 内 存 。 不 过 在 Elastic Stack 场景 中 ， 一 
般 不 会 用 到 这 个 特性 ， 所 以 此 处 数据 应 该 一 直 是 0。 


1. fielddata : 


"fielddata": { 
"memory size in bytes": 0, 
"evictions": 0 


ty 


此 处 显示 fielddata 使 用 的 内 存 大 小 。fielddata 用 来 做 聚合 ， 排 序 等 工作 。 


注意 : fielddata.evictions 应 该 永远 是 0。 一旦 发 现 这 个 数据 大 于 0， 请 立刻 检查 自 
己 的 内 存 配 置 ，fielddata 限制 以 及 请 求 语 名 。 


1. segments : 


"segments": { 
countu: 17 
"memory_in_bytes": 2042, 


"terms_memory_in_bytes" : 1510, 
"stored_fields_memory_in_bytes" : 312, 
"term_vectors_memory_in_bytes" : 0, 
"norms_memory_in_bytes" : 128, 
"points memory in bytes" : 0, 

"doc values memory in bytes" : 92, 
"index writer memory in bytes" : 0, 
"version map memory in bytes" : 0, 
"fixed bit set memory in bytes" : 0, 
"max unsafe auto id timestamp" : -1, 
"file sizes" : ( 3 


ty 


segments.count #7 $ & EPA #4] 4% segment 数目 的 总 和 。 一 般 来 说 ， 一 个 索 
引 通 常会 有 50-150 个 segments。 再 多 就 对 写 入 性 能 有 较 大 影响 了 (可 能 merge 3& 
度 跟 不 上 新 segment 出 现 的 速度 )。 所 以 ， 请 根据 节点 上 的 索引 数据 正确 评估 节点 
segment 的 情况 。 

segments.memory_in_bytes 表示 segments 本 身 底层 数据 结构 所 使 用 的 内 存 大 

小 。 像 索引 的 倒 排 表 ， 词 典 ，bloom filter(ES1.4 以 后 A 等 ， 都 是 要 在 
内 存 里 的 。 所 以 过 多 的 segments 会 导致 这 个 数值 迅速 变 大 。 


操作 系统 和 进程 信息 


al 系统 信 包括 CPU，Loadavg，Memory 和 Swap 利用 率 ， 文 件 句 柄 等 。 
这 些 内 容 都 是 常见 的 监控 项 ， 本 书 不 再 元 述 。 


进程 ， 即 JVM 信息 ， 主 要 在 于 GC 相关 数据 。 


GC 


对 不 了 解 JVM 的 GC 的 读者 ， 这 里 先 介绍 一 下 GC( 垃 圾 收集 ) 以 及 GC 对 
Elasticsearch 的 影响 。 


Java is a garbage-collected language, which means that the programmer does not 
manually manage memory allocation and deallocation. The programmer simply 
writes code, and the Java Virtual Machine (JVM) manages the process of 
allocating memory as needed, and then later cleaning up that memory when no 
longer needed. Java 是 一 个 自动 垃圾 收集 的 编程 语言 ， 启 动 SVM 虚拟 机 的 时 候 ， 
会 分 配 到 固定 大 小 的 内 存 块 ， 这 个 块 叫做 heap( 堆 )。JVM 会 把 heap 分 成 两 个 组 : 


© Young 13: I6 RON S PT feme 间 。 这 个 空间 一 般 来 说 只 有 100MB 到 
500MB 大 小 。Young 空间 又 分 为 两 个 a i 间 。 当 Young 空间 满 ， 
就 会 发 生 一 次 young gc， 还 存活 的 对 象 ， 就 被 移入 幸存 空间 里 ， 已 失效 的 对 象 
则 被 移 除 。 

| 闻 。 这 些 对 象 应 该 是 长 期 存活 而 且 在 较 长 一 段 时 间 内 不 会 
变化 的 内 容 。 这 个 空间 会 大 很 多 ， 在 ES 来 说 ， 一 节点 上 可 能 就 有 30GB 内 存 
是 这 个 空间 。 is 的 young gc 中 ， 如 果 某 个 对 象 连 续 多 次 幸存 下 来 ， 就 
会 被 移 进 Old 空间 内 。 而 等 到 Old 空间 满 ， 就 会 发 生 一 次 old gc， 把 失效 对 象 
移 除 。 


听 起 来 很 美好 的 样子 ， 但 是 这 些 都 是 有 代价 的 上 在 GC 发 生 的 时 候 ，JVM 需要 暂停 
ee ee 部 失效 对 象 。 在 这 期 间 ， 其 他 一 切 都 不 会 继 
运行 。 请 求 没有 响应 ，ping 没有 应 答 ， 分 片 不 会 分 配 ....….. 


当然 ，young gc 一 般 来 说 执行 极 快 ， 没 太 大 影响 。 但 是 old 空间 那么 大 ， 稍 慢 一 
的 gc 就 意味 着 程序 几 秒 乃至 十 几 秒 的 不 可 用 ， 这 太 危 除了 。 


JVM AF xt gc 算法 一 直 在 努力 优化 ，Elasticsearch 也 尽量 复 用 内 部 对 象 ， 复 用 网 

络 缓冲 ， 然 后 还 提供 像 Doc Values 这 样 的 特性 。 但 不 管 怎 么 说 ，gc 性 能 总 是 我 们 
需要 密切 关注 的 数据 ， 因 为 它 是 集群 稳定 性 最 大 的 影响 因子 。 

如 果 你 的 ES 集群 监控 里 发 现 经 常 有 很 耗 时 的 GC， 说 明 集群 负载 很 重 ， 内 存 不 

足 。 严 重 情况 下 ， 这 些 GC 导致 节点 无 法 正确 响应 集群 之 问 的 ping ， 可 能 就 直接 

从 集群 里 退出 了 。 然 后 数据 分 片 也 随 之 在 集群 中 重新 迁移 ， 引 发 更 大 的 网 络 和 磁盘 

lO ， 正 常 的 写 入 和 搜索 也 会 受到 影响 。 


在 节点 状态 数据 中 ， 以 下 部 分 就 是 SVM 相关 的 数据 : 


"jvm": { 

"timestamp": 1408556438203, 

"uptime_in_millis": 14457, 

"mem": { 
"heap_used_in_bytes": 457252160, 
"heap_used_percent": 44, 
"heap_committed_in_bytes": 1038876672, 
"heap_max_in_bytes": 1038876672, 
"non_heap_used_in_bytes": 38680680, 
"non_heap_committed_in_bytes": 38993920, 





ty 


首先 可 以 看 到 的 就 是 heap 的 情况 。 其 中 这 个 heap committed in bytes 指 的 
是 实际 被 进程 使 用 的 内 存 ， 以 JVM 的 特性 ， 这 个 值 应 该 等 于 

heap max in bytes ° heap used percent 则 是 一 个 更 直观 的 阅 值 数据 。 当 
这 个 数据 大 于 75% 的 时 候 ，ES 就 要 开始 GC。 也 就 是 说 ， 如 果 你 的 节点 这 个 数据 
长 期 在 75% 以 上 ， 说 明 你 的 节点 内 存 不 足 ，GC 可 能 会 很 慢 了 。 更 进一步 ， 如 果 到 
85% 或 者 95% 了 ， 估 计 节 点 一 次 GC 能 耗 时 10s 以 上 ， 甚 至 可 能 会 发 生 OOM 
Fo 


继续 看 下 一 段 : 


"pools": { 

"young": { 
"used_in_bytes": 138467752, 
"max_in_bytes": 279183360, 
"peak_used_in_bytes": 279183360, 
"peak_max_in_bytes": 279183360 

3 

"survivor": ( 
"used in bytes": 34865152, 
"max in bytes": 34865152, 
"peak used in bytes": 34865152, 
"peak max in bytes": 34865152 


ty 
poH a EET 
"used in bytes": 283919256, 
"max in bytes": 724828160, 
"peak used in bytes": 283919256, 
"peak max in bytes": 724828160 
j 


ty 


这 段 里 面 列 出 了 young, survivor, fe old GC 区 域 的 情况 ， 不 过 一 般 来 说 用 途 不 大 。 
再 看 下 一 段 : 


Co 
"collectors": { 
"young": ( 
"collection count": 13, 
"collection time in millis": 923 
tr 
POU. 
"collection count": 0, 
"collection time in millis": 0 
} 
} 


这 里 显示 的 young 和 old gc fj it Zt Fe 4€ » young gc 的 count 一 般 比 较 大 ， 这 是 
正常 情况 。old gc 的 count 应 该 就 保持 在 比较 小 的 状态 ， 包 括 耗 时 的 

collection time in millis 也 应 该 很 小 。 注 意 这 两 个 计数 都 是 累计 的 ， 所 以 
对 于 一 个 长 期 运行 的 系统 ， 不 能 拿 这 个 数值 直接 做 报警 的 判断 ， 应 该 是 取 两 次 节点 
数据 的 差 值 。 有 了 差 值 之 后 ， 再 来 看 耗 时 的 问题 ， 一 般 来 说 ， 一 次 young gc 的 耗 
时 应 该 在 1-2 ms，old gc 在 100 ms 的 水 平 。 如 果 这 个 耗 时 有 量 级 上 的 差距 ， 建 议 
打开 slow-GC 上 日志， 具体 研究 原因 。 


线程 池 信 息 


Elasticsearch 内 部 是 保持 着 几 个 线程 池 的 ， 不 同 的 工作 由 不 同 的 线程 池 负 责 。 一 般 
来 说 ， 每 个 池子 的 工作 线程 数 跟 你 的 CPU 核 数 一 样 。 之 前 有 传言 中 的 优化 配置 是 

加 大 这 方面 的 配置 项 ， 其 实 没 有 什么 实际 帮 活 的 CPU 就 那么 些 个 数 。 
所 以 这 段 状态 数据 目的 不 是 用 作 ES 配置 调 优 ， 而 是 作为 性 能 监控 ， 方 便 优化 你 的 

读 写 请 求 。 





ES 在 index、bulk、search、get、merge 等 各 种 操作 都 有 专门 的 线程 池 ， 大 家 的 
统计 数据 格式 都 是 类 似 的 : 


"index": { 
"threads": 1, 
"queue": 0, 
"active": ©, 
"rejected": 0, 
"largest": 1, 
"completed": 1 


这 些 数据 中 ， 最 重要 的 是 rejected 数据 。 当 线程 中 中 所 有 的 工作 线程 都 在 忙 ， 即 

active == threads， 后 续 的 请 求 就 会 暂时 放 到 排队 的 队列 里 ， 即 queue > 0。 但 是 

queue 也 是 有 大 小 限制 的 ， 上 默认 是 100。 如 果 后 续 请 求 超过 这 个 大 
| 意味 着 ES 览 的 接受 不 过 来 这 个 请 求 了 ， 就 会 把 后 续 请 求 reject 4$ ° 


Bulk Rejections 


如 果 你 确实 注意 到 了 上 面 数据 中 的 rejected， 很 可 能 就 是 你 在 发 送 bulk E A kg 8 4& 
碰 到 HTTP 状态 码 429 的 响应 报错 了 。 事 实 上 ， 集 群 的 承载 能 力 是 有 上 限 的 。 如 果 
你 集群 每 秒 就 能 写 入 10000 条 数据 ， 以 其 浪费 内 存 多 放 几 条 数据 在 排队 ， 还 不 如 直 
接 拒 绝 掉 。 至 少 可 以 让 你 知道 到 瓶颈 了 。 


另外 有 一 点 可 以 指出 的 是 ， 因 为 bulk queue 里 的 数据 是 维护 在 内 存 中 ， 所 以 节点 
发 生意 外 死机 的 时 候 ， 是 会 丢失 的 。 


如 果 你 碰 到 bulk rejected， 可 以 尝试 以 下 步骤 : 


1. 暂停 所 有 的 写 入 进程 。 

2. 从 bulk 响应 中 过 滤 出 来 rejected 的 那 部 分 。 因 为 bulk index 中 可 能 大 部 分 已 
经 成 功 了 。 

3. 重 发 一 次 失败 的 请 求 。 

4. 恢复 写 入 进程 ， 或 者 重新 来 一 次 上 述 步 


大 家 可 能 看 出 来 了 ， 没 错 ， 对 rejected 其 实 压根 没什么 特殊 的 操作 ， 重 试 一 次 而 
i o 


当然 ， 如 果 这 个 rejected 是 持续 存在 并 增长 的 ， 那 重 试 也 无 济 于 事 。 你 可 能 需要 考 
虑 自己 集群 是 否 足 以 支撑 当前 的 写 入 速度 要 求 。 


pce ， 那么 可 能 是 因为 客户 端 并 发 太 多 ， 超 过 集群 的 bulk threads 总 数 
尝试 减少 自己 的 写 入 进程 个 数 ， 改 成 加 大 每 次 bulk 请 求 的 size © 


文件 系统 和 网 络 


数据 继续 往 下 走 ， 是 文件 系统 和 网 络 的 数据 。 文 件 系 统 方面 ， 不 管 是 剩余 空间 还 
IO 数据 ， 都 推荐 大 家 还 是 通过 更 传统 的 系统 层 监 控 手 段 来 做 。 0 
要 有 两 部 分 内 容 


"transport": { 
"server_open": 13, 
"rx_count": 11696, 
"rx_size_in_bytes": 1525774, 
"tx_count": 10282, 
"tx_size_in_bytes": 1440101928 


ty 
alt de AE 
"current open": 4, 
"total opened": 23 
ty 


我 们 知道 ES 同时 运行 着 transport 和 http > Ki $Æ 9300 和 9200 3 9 » HT 
ES 使 用 了 一 些 transport 连接 来 维护 节点 内 部 关系 ， 所 以 
transport.server_open 正常 情况 下 一 直 会 有 一 定 大 小 。 而 
http.current open 则 是 实际 连接 上 来 的 HTTP. 客户 端的 数量 ， 考 虑 到 HTTP 
建 联 的 消耗 ， 强 烈 建议 大 家 使 用 keep-alive 长 连接 的 客户 端 。 


Circuit Breaker 


继续 往 下 ， 是 circuit breaker 的 数据 ， 包 括 request ^ fielddata ` in flight requests 


和 parent 四 种 : 


"in flight requests": { 
"maximum size in bytes": 623326003, 
"maximum size": "594.4mb", 
"estimated size in bytes": 0, 
"estimated size": "Ob", 

"overhead": 1.03, 
"tripped": 0 


in flight requests 是 5.0 RAB Ia A 89 — JE o AHAMAP > HIRE > 
而 入 口 流 量 过 大 会 导致 Client 节点 在 分 发 bulk AZ " 时 候 没 有 限 速 而 OOM * BLE 


可 以 直接 对 过 大 的 流量 返回 失败 了 。 


ingest 
最 后 是 ingest 节点 独 有 的 ingest 状态 数据 。 


"ingest" : { 
"rotal' i 
"count" : 0, 
"time_in_millis" : 0， 
"current" : 0, 
"failed" : 0 
tr 
"pipelines" : { 
"set-something" : { 
"count" : 0, 
"time_in_millis" : 0， 
"current" : ©, 
"failed" : 0 


会 列 出 每 个 定义 好 的 pipeline 以 及 最 终 总 体 的 ingest 处 理 量 、 当 前 处 理 中 的 数据 量 
和 处 理 耗 时 等 。 


hot threads 状态 
余 了 stats 信息 以 外 ， /_nodes/ 下 还 有 另 一 个 监控 接口 : 


# curl -XGET 'http://127.0.0.1:9200/ nodes/ local/hot threads?in 
terval-60s' 


该 接口 会 返回 在 interval 时 长 内 ， 该 节点 消耗 资源 最 多 的 前 三 个 线程 的 堆栈 情 
况 。 这 对 于 性 能 调 优 初期 ， 采 集 现状 数据 ， 极 为 有 用 。 


默认 的 采样 间隔 是 500ms， 一 般 来 说 ， 这 个 时 间 范 围 是 不 太 够 的 ， 建 议 至 少 60s 
以 上 。 


默认 的 ， 资 源 消耗 是 按照 CPU 来 衡量 ， 还 可 以 用 ?type-wait RA ? 
type=block 来 查看 在 等 待 和 堵塞 状态 的 当前 线程 排名 。 


索引 状态 监控 接口 


索引 状态 监控 接口 的 输出 信息 和 节点 状态 监控 接口 非常 类 似 。 一 般 情 况 下 ， 这 个 接 
口 单独 监控 起 来 的 意义 并 不 大 。 
过 在 ES 1.6 版 开始 ， 加 入 了 对 索引 分 片 级 别 的 commit id 功能 。 

回忆 一 下 之 前 原理 章节 的 内 容 ，commit 是 在 分 片 内 部 ， 对 每 个 segment 做 的 。 而 
数据 在 主 分 片 和 副本 分 片上 ， 是 由 各 自 节点 自行 做 Segment merge 操作 ， 所 以 副 
e 分 片 和 主 分 片 的 segment 的 commit id 是 不 一 致 的 。 这 导致 ES 副本 恢复 时 ， 跟 

主 分 片 比 对 commit id， 基 本 上 每 个 segment 都 不 一 样 ， 所 以 才 需 要 从 主 分 片 完 整 
重 传 一 份 数据 。 


新 加 入 分 片 级 别 的 commit id 后 ， 副 本 恢复 时 ， 先 比 对 跟 主 分 片 的 分 片 级 commit 
id， 如 果 一 致 ， 直 接 本 地 恢复 副本 分 片 内 容 即 可 。 


查看 分 片 级 别 commit id 的 命令 如 下 : 


# curl 'http://127.0.0.1:9200/10gstash-mweibo-2015.06.15/ stats/ 
commit?level-shards&pretty' 


"indices" : { 
"logstash-2015.06.15" : { 
"primaries" : { }, 
EODD a (S 
"shards" : ( 
pO SE 
"routing" : { 
"state" : "STARTED", 
"primary" : true, 
"node" : "AqaYWFQJRIKOZydvVgASEw", 
"relocating_node" : null 
ty 
"commit" : { 
"generation" : 726, 
"user_data" : { 
"translog_id" : "1434297603053", 
"sync id" : "AUALEh6wnBE6nOqcEXs5" 
ty 


"num_docs" : 36792652 


3l 


注意 : 为 了 节约 频繁 变更 的 资源 消耗 ，ES 并 不 会 实时 更 新 分 片 级 commit id。 只 有 
连续 5 分 钟 没有 新 数据 写 入 的 索引 ， 才 会 触发 给 索引 各 分 片 更 新 commit id 的 操 
作 。 如 果 你 查看 的 是 一 个 还 在 新 写 入 数据 的 索引 ， 看 到 的 内 容 应 该 是 下 面 这 样 : 


"commit" : { 
"generation" : 590, 
"user data" : { 
"translog id" : "1434038402801" 


13 
"hum docs" : 29051938 


421 


任务 管理 


m 


任务 是 Elasticsearch 中 早 就 有 的 一 个 概念 。 不 过 最 新 的 5.0 版 对 此 重 构 之 前 ， 我 
们 只 能 看 到 对 于 master 来 说 等 待 执行 的 集群 级 别 的 任务 。 这 个 是 一 个 非常 狭隘 的 
概念 。 重 构 以 后 ， 和 数据 相关 的 一 些 操作 ， 也 可 以 以 任务 形态 存在 ， 从 而 也 就 有 了 
针对 性 的 管理 操作 。 目 前 ， 还 只 有 recovery ` snapshot ` reindex 等 操作 是 基于 任 
务 式 的 。 未 来 的 6.0 版 ， 可 能 把 整个 query 检索 都 改 为 基于 任务 式 的 。 困 扰 用 户 多 
年 的 资源 隔离 问题 ， 可 能 就 可 以 得 到 大 大 缓解 。 


等 待 执行 的 任务 列表 


首先 我 们 还 是 先 了 解 一 下 狭义 的 任务 ， pee 就 有 的 master 节点 的 等 待 执行 任 
务 。 之 前 章节 已 经 讲 过 ，master 节点 负责 处 理 的 任务 其 实 很 少 ， 只 有 集群 状态 的 数 
据 维 护 。 所 以 绝 大 多 数 情况 下 ， ea 该 都 是 空 的 。 


# curl -XGET http://127.0.0.1:9200/_cluster/pending_tasks 


{ 
"tasks": [] 


12 JE de RUG E E AEA HH ^ Hote A RIRA EH > BAER AM 2-5 PRK 
者 初始 化 的 时 候 反 复出 错 啊 这 种 时 候 ， 就 会 看 到 一 些 任 务 列表 了 : 


tasKs a DT 
"insert_order": 767003, 
"priority": "URGENT", 
"source": "create-index [logstash-2015.06.01], cause [api]", 
"time_in_queue_millis": 86, 
"time in queue": "86ms" 
}, { 
"insert_order" : 767004, 
"priority" : "HIGH", 
"source" : "shard-failed ([logstash-2015.05.31][50], node[F3 
EGSRWGSvWGFlcZ6K9pRA], [P], s[INITIALIZING]), reason [shard fail 


ure [failed recovery] [IndexShardGatewayRecoveryException[[logsta 
sh-2015.05.31][50] failed to fetch index version after copying i 
t over]; nested: CorruptIndexException[[logstash-2015.05.31][50] 
Preexisting corrupted index [corrupted nC9t ramRHqsbQqZ078KVg] 
caused by: CorruptIndexException[did not read all bytes from fil 
e: read 269 vs size 307 (resource: BufferedChecksumIndexInput(NI 
OFSIndexInput (path=\"/data1/elasticsearch/data/es1003/nodes/0/in 
dices/logstash-2015.05.31/50/index/_16c.si ")))]\norg.apache. luc 
ene. index.CorruptIndexException: did not read all bytes from fil 
e: read 269 vs size 307 (resource: BufferedChecksumIndexInput (NI 
OFSIndexInput (path=\"/datai/elasticsearch/data/es1003/nodes/0/in 
dices/logstash-2015.05.31/50/index/_16c.si \")))\n\tat org.apache 
. Lucene.codecs.CodecUtil.checkFooter(CodecUtil.java:216)\n\tat o 
rg.apache.lucene.codecs.lucene46.Lucene46SegmentInfoReader.read( 
Lucene46SegmentInfoReader.java:73)NnNtat org.apache.lucene.index 
.SegmentInfos.read(SegmentInfos.java:359)NnNtat org.apache.lucen 
e.index.SegmentInfos$1.doBody(SegmentInfos.java:462)NnNtat org.a 
pache.lucene.index.SegmentInfos$FindSegmentsFile.run(SegmentInfo 
S.java:923)\n\tat org.apache.lucene.index.SegmentInfos$FindSegme 
ntsFile.run(SegmentInfos.java:769)NnNtat org.apache.lucene.index 
.SegmentInfos.read(SegmentInfos.java:458)NnNtat org.elasticsearc 
h.common.lucene.Lucene.readSegmentInfos(Lucene.java:89)NnNtat or 
g.elasticsearch.index.store.Store.readSegmentsInfo(Store.java:15 
8)\n\tat org.elasticsearch.index.store.Store.readLastCommittedSe 
gmentsInfo(Store.java:148)NnNtat org.elasticsearch.index.engine. 
InternalEngine.flush(InternalEngine.java:675)NnNtat org.elastics 
earch.index.engine.InternalEngine.flush(InternalEngine.java:593) 
\n\tat org.elasticsearch.index.shard.IndexShard.flush(IndexShard 
.java:675)\n\tat org.elasticsearch.index.translog.TranslogServic 
e$TranslogBasedFlush$1.run(TranslogService.java:203)NnNtat java. 
util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor. 
java:1142)\n\tat java.util.concurrent.ThreadPoolExecutor$Worker. 
run(ThreadPoolExecutor.java:617)NnNtat java.lang.Thread.run(Thre 
ad.java:745)Nn]; ]]', 

"executing" : true, 

"time in queue millis" : 2813, 

"time in queue" : "2.8s" 

j, 1 
"insert order" : 767005, 
"priority" : "HIGH", 


"source" : "refresh-mapping [logstash-2015.06.03][[curl debu 
ginfo]]", 

"executing" : false, 

"time in queue millis" : 2787, 

"time in queue" : "2.7s" 

} { 

"insert_order" : 767006, 

"priority" : "HIGH", 

"source" : "refresh-mapping [logstash-2015.05.29][[curl debu 
ginfo]]", 

"executing" : false, 

"time in queue millis" : 448, 

"time in queue" : "448ms" 


1-1 


可 以 看 到 列表 中 的 任务 都 有 各 自 的 优先 级 ，URGENT 优先 于 HIGH 。 然 后 是 任务 在 
队列 中 的 排队 时 间 ， 任 务 的 具体 内 容 等 。 


在 上 例 中 ， 由 于 磁盘 文件 损坏 ， 一 个 分 片 中 某 个 segment 的 实际 内 容 和 长 度 对 不 

上 ， 导 致 分 片 数据 恢复 无 法 正常 完成 ， 堵 塞 了 后 续 的 索引 映射 更 新 操作 。 这 个 错误 
一 般 来 说 不 太 常 见 ， 也 只 能 是 关闭 索引 ， 或 者 放弃 这 部 分 数据 。 更 常见 的 可 能 ， 是 
集群 存储 长 期 数据 导致 索引 映射 数据 确实 大 到 了 master 节点 内 存 不 足以 快速 处 理 
的 地 步 。 


这 时 候 ， 根 据 实 际 情况 ， 可 以 有 以 下 几 种 选择 : 


e 索引 就 是 特别 多 : 给 master 加 内 存 。 
e 索引 里 字段 太 多 : AA nested object 方式 节省 字段 数量 。 
e 索引 多 到 内 存 就 是 不 够 了 : 把 一 部 分 数据 拆 出 来 另 一 个 集群 。 


新 版 任务 管理 


新 版 本 的 任务 并 没有 独立 的 创建 接口 ， 你 发 起 的 具体 某 次 snapshot、reindex 等 操 
作 ， 自 动 就 成 为 了 一 个 任务 。 而 任务 的 列表 可 以 通过 / tasks 或 者 
/_cat/tasks 接口 来 获取 。 和 其 他 接口 一 样 ， 手 工 操 作 选 用 cat ， 写 程序 的 时 候 
选用 JSON 接口 。 


curl -XGET 'localhost:9200/_cat/tasks?v' 


action task id parent 
task id type start time timestamp running t 
ime ip node 

cluster:monitor/tasks/lists -ANcpn JTI-Zs93fGAfhjw:779 - 


transport 1477891751674 13:29:11 170.2micr 
os 127.0.0.1 -ANcpn. 
cluster:monitor/tasks/lists[n] -ANcpn JTI-Zs93fGAfhjw:780 -ANcpn 
—JTI-Zs93fGAfhjw:779 direct 1477891751674 13:29:11 60.6micro 
S 127.0.0.1 -ANcpn 
indices:data/write/reindex r1A2WORbDTWKZ516z6NESs5A:916 - 
transport 1477891751674 13:29:11 212.5micr 
os 127.0.0.1 riA2WoR 


上 面 是 一 个 正常 运行 中 的 集群 的 任务 列表 。 除 了 一 个 reindex 任务 ， 没 有 什么 
recovery 的 麻烦 事 儿 ， 很 好 。 


如 果 想 要 取消 某 个 任务 ， 比 如 上 面 的 reindex， 可 以 像 这 样 运 行 : 


curl -XPOST 'localhost:9200/ tasks/task id:916/ cancel' 


目前 来 说 ， 能 做 的 只 有 这 些 了 。Elasticsearch 还 不 支持 诸如 挂 起 、 暂 停 之 类 更 复杂 
的 任务 操作 。 让 我 们 期 待 未 来 的 发 展 吧 。 


cat 接口 的 命令 行使 用 


之 前 介绍 的 各 种 接口 数据 ， 其 响应 数据 都 是 JSON 格式 ， 更 适用 于 程序 处 理 。 对 于 
我 们 日 常 运 维 ， 在 Linux 命令 行 终端 环境 来 说 ， 简 单 的 分 行 和 分 列表 格 才 是 更 方便 
的 样式 。 为 此 ，Elasticsearch 提供 了 cat 接口 。 


cat 接口 可 以 读 取 各 种 监控 数据 ， 可 用 接口 列表 如 下 : 


e / cat/nodes 

e / cat/shards 

e / cat/shards/(index) 

e / cat/aliases 

e / cat/aliases/(alias) 

e / cat/tasks 

e / cat/master 

e / cat/plugins 

e / cat/fielddata 

e / cat/fielddata/{fields} 
e / cat/pending tasks 

e / cat/count 

e / cat/count/{index} 

e / cat/snapshots/(repository) 
e / cat/recovery 

e / cat/recovery/{index} 
e / cat/segments 

e / cat/segments/{index} 
e / cat/thread pool 

e / cat/thread pool/(thread pools cat/nodeattrs 
e / cat/allocation 

e / cat/repositories 

e / cat/health 

e / cat/indices 

e / cat/indices/(index) 


集群 状态 


还 是 以 最 基础 的 集群 状态 为 例 ， 采 用 cat 接口 查询 集群 状态 的 命令 如 下 : 


# curl -XGET http://127.0.0.1:9200/_cat/health 
1434300299 00:44:59 es1003 red 39 27 2589 1505 4 1 © 0 - 100.0% 


qo RY ARH ^ SQUE ENS S9 HP AUR EER o PUR ?v 参数 ， 输 
出 表 头 : 


# curl -XGET http://127.0.0.1:9200/_cat/health?v 

epoch timestamp cluster status node.total node.data shards 
pri relo init unassign pending tasks max task wait time active 
shards percent 





1434300334 00:45:34 es1003 green 39 27 2590 
1506 5 0 0 0 = 
100. 0% 


节点 状态 


# curl -XGET http://127.0.0.1:9200/_cat/nodes?v 


host ip heap.percent ram.percent load_im load_5m 
load 15m node.role master name 
esnode109 10.19.0.109 62 69 6.37 
d - 10.19.0.109 
esnode096 10.19.0.96 63 69 0.29 
- - 10.19.0.96 
esnode100 10.19.0.100 56 79 0.07 
- m 10.19.0.100 


跟 集群 状态 不 一 样 的 是 ， 节 点 状态 数据 太 多 ，cat 接口 不 方便 在 一 行 表格 中 放下 所 
有 数据 。 所 以 默认 的 返回 ， 只 是 最 基本 的 内 存 和 负载 数据 。 具 体 想 看 某 方面 的 数 
据 ， 也 是 通过 请 求 参 数 的 方式 额外 指明 。 比 如 想 看 heap 百分比 和 最 大 值 : 


# curl -XGET 'http://127.0.0.1:9200/ cat/nodes?v&h-ip, port, heapP 
ercent, heapMax' 

ip port heapPercent heapMax 

192.168.1.131 9300 66 25gb 


h 请 求 参数 可 用 的 值 ， 可 以 通过 ?help 请 求 参 数 来 查询 : 


# curl -XGET http://127.0.0.1:9200/_cat/nodes?help 


id | id,nodeId | unique node id 

host | h | host name 

ip gest | ip address 

port | po | bound transport por 

t 

heap.percent | hp, heapPercent | used heap ratio 

heap.max | hm, heapMax | max configured heap 
ram.percent | rp,ramPercent | used machine memory 
ratio 

ram.max | rm, ramMax | total machine memor 

y 

load | 1 | most recent load av 

g 

node.role | r,role,dc,nodeRole | d:data node, c:clie 

nt node 


中 间 第 三 列 就 是 对 应 的 请 求 参数 的 值 及 其 缩写 。 也 就 是 说 上 面 示例 还 可 以 写成 : 


# curl -XGET http://127.0.0.1:9200/_cat/nodes?v&h=i, po, hp, hm 


索引 状态 


查询 索引 列表 和 存储 的 数据 状态 是 也 是 cat 接口 最 常用 的 功能 之 一 。 为 了 方便 阅 
读 ， 默 认输 出 时 会 把 数据 大 小 以 更 可 读 的 方式 自动 换算 成 合适 的 单位 ， 比 如 3.2tb 
这 样 。 


如 果 你 打算 通过 shell 管道 做 后 续 处 理 ， 那 么 可 以 加 上 bytes 参数 ， 指 明 统一 
采用 字 节 数 输出 ， 这 样 保证 在 同一 个 级 别 上 排序 : 


# curl -XGET http://127.0.0.1:9200/_cat/indices?bytes=b | sort - 
rnk8 


green open logstash-mweibo-2015.06.12 261 754641614 0 
2534955821580 1256680767317 
green open logstash-mweibo-2015.06.14 27 1 855516794 0 


2419569433696 1222355996673 


分 片 状态 
# curl -XGET http://127.0.0.1:9200/_cat/shards?v 
index shard prirep state 
docs store ip node 
logstash-mweibo-h5view-2015.06.10 20 p STARTED 469 
0968 679.2mb 127.0.0.1 10.19.0.108 
logstash-mweibo-h5view-2015.06.10 20 r STARTED 469 
0968 679.4mb 127.0.0.1 10.19.0.39 
logstash-mweibo-h5view-2015.06.10 2 p STARTED 472 
5961 684.3mb 127.0.0.1 10.19.0.53 
logstash-mweibo-h5view-2015.06.10 2 r STARTED 472 


5961 684.3mb 127.0.0.1 10.19.0.102 


同样 ， 可 以 用 ?help 查询 其 他 可 用 数据 细节 。 比 如 每 个 分 片 的 segment.count : 


# curl -XGET 'http://127.0.0.1:9200/_cat/shards/logstash-mweibo- 
nginx-2015.06.14?v\&h=n, iic,sc' 


n 11C SC 
10.19.0.72 © 42 
10.19.0.41 0 36 
10.19.0.104 0 32 
10.19.0.102 © 40 


恢复 状态 


在 出 现 集 群 状态 波动 时 ， 通 过 这 个 接口 查看 数据 迁移 和 恢复 速度 也 是 一 个 非常 有 用 
ee n 
一 般 会 加 上 ?active only 参数 ， 仅 列 出 当前 还 在 运行 的 恢复 状态 : 


# curl -XGET 'http://127.0.0.1:9200/_cat/recovery?active_only&v& 
h-i,s,shost,thost,fp,bp,tr,trp,trt' 

i S shost thost fp bp tr 
trp trt 

logstash-mweibo-2015.06.12 10 esnode041 esnode080 87.6% 35.3% 0 
100.0% 0 

logstash-mweibo-2015.06.13 10 esnode108 esnode080 95.5% 88.3% 0 
100.0% 0 

logstash-mweibo-2015.06.14 17 esnode102 esnode080 96.3% 92.5% 0 
0.0% 118758 


线程 池 状 态 


curl -s -XGET http://127.0.0.1:9200/_cat/thread_pool?v 


node_name name active queue rejected 
esnode073 bulk 1 0 20669 
esnode073 fetch_shard_started 0 0 0 
esnode073 fetch shard store 0 0 0 
esnode073 flush 0 0 0 
esnode073 force merge 0 0 0 
esnode073 generic 0 0 0 
esnode073 get 0 0 0 
esnode073 index 0 0 50 
esnode073 listener 0 0 0 
esnode073 management 1 0 0 
esnode073 refresh 0 0 0 
esnode073 search 4 0 0 
esnode073 snapshot 0 0 0 
esnode073 warmer 0 0 0 


这 个 接口 的 输出 形式 和 5.0 之 前 的 版 本 有 了 较 大 变化 ， 把 不 同类 型 的 线程 状态 做 了 
一 次 行列 转换 ， 大 大 减少 了 列 数 以 后 ， 对 人 眼 更 加 合适 了 。 
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A 志 记 录 


Elasticsearch 作为 一 个 服务 ， 本 身 也 会 记录 很 多 日 志 人 信息。 默认 情况 下 ， 日 志 都 放 
在 $ES HOME/logs/ 目录 里 。 


日 志 配 置 在 Elasticsearch 5.0 中 改 成 了 使 用 1og4j2.properties 文件 配置 ， 包 

括 日 志 滚动 的 方式 、 命 名 等 ， 都 和 标准 的 log4j2 一 样 。 唯 一 的 特点 是 : 
Elasticsearch 导出 了 一 个 变量 叫 ${sys:es.logs} ， 指 向 你 在 
elasticsearch.yml 中 配置 的 path.logs 地 址 : 


appender.index search slowlog rolling.filePattern = ${sys:es.log 
s index search slowlog-9?6d([yyyy-MM-dd).log 


具体 的 级 别 等 级 也 可 以 通过  / cluster/settings 接口 动态 调整 。 比 如 说 ， 如 果 
你 的 节点 一 直 无 法 正确 的 加 入 集群 ， 你 可 以 将 集群 自动 发 现 方面 的 日 志 级 别 修改 成 
DEBUG ， 来 关注 这 方面 的 问题 : 


# curl -XPUT http://127.0.0.1:9200/_cluster/settings -d' 
{ 


"transient" : { 
"logger.org.elasticsearch.indices.recovery" : "DEBUG" 


性 能 日 志 
除了 进程 状态 的 日 志 输 出 ，ES 还 支持 跟 性 能 相关 的 日 志 输 出 。 针 对 数据 写 入 ， 检 
索 ， 读 取 三 个 阶段 ， 都 可 以 设置 具体 的 慢 查询 阅 值 ， 以 及 不 同 的 输出 等 级 。 


此 外 ， 慢 查询 日 志 是 针对 索引 级 别 的 设置 。 除 了 通过 /_cluster/settings 接口 
配置 一 组 集群 各 索引 共用 的 参数 以 外 ， 还 可 以 针对 每 个 索引 设置 不 同 的 参数 。 


注 : 过 去 的 版 本 ， 还 可 以 在 elasticsearch.yml 中 设置 ，5.0 版 禁止 在 配置 文件 
中 添加 索引 级 别 的 设置 ! 


比如 说 ， 我 们 可 以 先 设置 集群 共同 的 参数 : 


# curl -XPUT http://127.0.0.1:9200/_cluster/settings -d' 
{ 


"transient" : { 
"logger.index.search.slowlog" : "DEBUG", 
"logger.index.indexing.slowlog" : "WARN", 
"index.search.slowlog.threshold.query.debug" : "10s", 


"index.search.slowlog.threshold.fetch.debug": "500ms", 
"index.indexing.slowlog.threshold.index.warn": "5s" 


} 1 


然后 针对 某 个 比较 大 的 索引 ， 调 高 设置 : 


# curl -XPUT http://127.0.0.1:9200/logstash-wwwlog-2015.06.21/_s 

ettings -d' 

f 
"index.search.slowlog.threshold.query.warn" : "10s", 
"index.search.slowlog.threshold.fetch.debug": "500ms", 
"index.indexing.slowlog.threshold.index.info": "10s" 


bigdesk 


要 想 最 快 的 了 解 ES 各 节点 的 性 能 细节 ， 推 荐 使 用 bigdesk 插件 ， 其 原作 者 为 
lukas-vlcek。 但 是 从 Elasticsearch 1.4 版 本 开始 就 不 再 更 新 了 。 国 内 有 用 户 fork 出 
来 继续 维护 到 支持 5.0 版 本 ，GitHub 地 址 见 : https://github.com/hlstudio/bigdesk 


bigdesk 通过 浏览 器 直 连 ES 节点 ， 发 起 RESTful 请 求 ， 并 泻 沫 结果 成 图 。 所 以 其 
安装 部 署 极其 简 3 


# git clone https://github.com/hlstudio/bigdesk 
# cd bigdesk/ site 


# python -mSimpleHTTPServer 
Serving HTTP on 0.0.0.0 port 8000 ... 


浏览 器 打开 http://localhost:8000 即 可 看 到 bigdesk  @ » & endpoint 4 
入 框 内 填写 要 连接 的 ES 节点 地 址 ， 选 择 refresh 间隔 和 keep 时 长 ， 点 击 
connect， 完 成 。 








127.0.0.1:8000/#nodes aarm Osa Fan Q 
1 sec 
ES node REST endpoint nttp://192.168.0.2:9200 Refresh ever v 2 sec Keep|5min s|history | connec 
nodes cluster 3 sec 
5 sec 
10 sec 
EES 


注意 : 设置 refresh 间隔 请 考虑 Elastic Stack 使 用 的 template 里 实际 的 


refresh interval 是 多 少 。 否 则 你 可 能 看 到 波动 太 大 的 数据 ， 不 足以 说 明 情 
Du ° 


点 选 某 个 节点 后 ， 就 可 以 看 到 该 节点 性 能 的 实时 走势 。 一 般 重 点 关注 JVM 性 能 和 
索引 性 能 9 


A X SVM 部 分 截图 如 下 


实时 bigdesk 方 案 





ES node REST endpoint nttp://10.19.0.101:9200 


Refresh every 2 sec B Keep sm» B history Disconnect 








nodes cluster 





Cluster: es1003 
Number of nodes: 39 


Status: yellow. 


Selected node: 


Name: 10.19.0.45 
ID: hObi3kjxXSia7 GABZ330ddw 





[10.19.0.100 |[10.19.0.101 |[10.19.0.102][10.19.0.103 | 10.19.0.104 |[10.19.0.105 || 10.19.0.106 ][ 10.19.0.107 ][10.19.0.108 | 











[Toxo rossa [oen [oso Ergo 








[10.19.0.64]] 10.19.0.65]| 10.19.0.66]| 10.19.0.67 |[10.19.0.68 || 10.19.0.69 ][ 10.19.0.70 ][10.19.0.72 | 10.19.0.73 || 10.19.0.74 | 





[rosas] A [rna [1.12080] rosea Jove 0.15096] 1.097] [1635326] [619255] 


Hostname: esnode045.mweibo.bx.sinanode.com 


Elasticsearch version: 1.6.0 





JVM 


VM name: Java HotSpot(TM) 64-Bit Server VM 


VM vendor: Oracle Corporation 
VM version: 25.45-b02 


Heap Mem 


Uptime: 5d 


Java version: 1.8.0 45 


PID: 32476 


Non-Heap Mem 





03:59 O4PM 0401 0402 


"Threads 
Zim 200 
150 
100 
o Peak 50 
o Count 





03:59 “04PM 0401 0402 











Committed: 25gb Committed: 112.3mb Peak: 222 Total time (O/Y): Oms / 2720981ms 
Used: 20gb Used: 110.1mb Count: 172 Total count (O/Y): 0 / 35760 
Thread Pools 
Index Refresh 
一 一 15 Ce 
3 
10 
H 2 
o Queue 5 o Queue 
o Peak o Peak 1 








o Count 















o Count 








03:599 O4PM 04:01 04:02 03:599 04PM 04:01 04:02 
Queue: 0 Queue: 0 Queue: 0 Queue: 0 
Peak: 25 Peak: 16 Peak: 16 Peak: 4 
Count: 0 Count: 0 Count: 6 Count: 0 
me 


有 关 数 据 读 写 性 能 部 分 截图 如 下 : 
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Um 
ES 


p 
Pid 
c. 
Q 
Q 
D 
o 
o 
` 
i 























File Descriptors 40k CPU (%) 
30k 
20k 
o Max 10k 
“0 B 
03:59 04 PM 04:01 04:02 04: 
Max: 32000 Total virtual: 576.1gb Series:| weighted avg € | Total: 1600% 
Open: 4017 Resident: 28.7gb Sys total: 81179190ms Process: 0% 
Share: 1.1gb User total: 1805149460ms 
HTTP & Transport 
HTTP address: Transport address: Transport size (A) 
inet[/10.19.0.45:9300] 
Bound address: 
Bound address: 
Publish address: inet[/0:0:0:0:0:0:0:0760:9300] 
Publish address: 
inet[/10.19.0.45:9300] 
Transport: n/a Series:| weighted avg + 
HTTP: n/a Rx: 1.1tb, 4573723448 
HTTP total opened: na Tx: 510.4gb, 4573108098 
Indices 
Docs count: 2315178851 Flush: 33105, 3.7h Size: 1.5tb 
Docs deleted: 0 Refresh: 139538, 5.8h 
Search requests per second (A) 6 Search time per second (A) Get requests per second (A) Get time per second (A) 
20k 
15k 
10k 
5k 
0 
03:59 04PM 04:01 04:02 04:03 
Query: 67219 Query: 1.8d 
Fetch: 239 Fetch: 3.7s 
Cache size Cache evictions (A) 
2G 
=o lD 1G 
o Filter 
o Field 





ID: 0b 


Eiern A 





Delete: 0 


Inclaws 127000204£& 


Filter: 787593 


Cinta 109 
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cerebro 


cerebro 这 个 名 字 大 家 可 能 觉得 很 陌生 ， 其 实 它 就 是 过 去 的 kopf 插件 ! AA 
Elasticsearch 5.0 不 再 支持 site plugin， 所 以 kopf 作者 放弃 了 原 项 目 ， 另 起 炉灶 搞 
了 cerebro， 以 独立 的 单 页 应 用 形式 ， 继 续 支 持 新 版 本 下 Elasticsearch 的 管理 工 
作 。 


项 目地 址 : https://github.com/Imenezes/cerebro 


单 页 应 用 的 安装 方式 都 非常 简单 ， 下 载 打 开 即 可 : 


# git clone https://github.com/lmenezes/cerebro 
# cd cerebro 
4 ./bin/cerebro 


然后 浏览 器 打开 http://localhost:9000 FP 7 ° 


zabbix 


之 前 提 到 的 都 是 Elasticsearch 的 sites 类 型 插件 ， 其 实质 是 实时 从 浏览 器 读 取 
cluster stats 接口 数据 并 泻 染 页 面 。 这 种 方式 直观 ， 但 不 适合 生产 环境 的 自动 化 监 
控 ce 要 达到 这 个 目标 ， 还 是 需要 使 用 诸如 nagios、zabbix、ganglia、 
collectd 3x X 35 4 A Zi 


本 节 以 zabbix 为 例 ， 介 绍 如 何 使 用 监控 系统 完成 Elasticsearch 的 监控 报警 。 


github 上 有 好 几 个 版 本 的 ESZabbix 仓库 ， 都 源 自 Elastic 公司 员工 untergeek 最 早 
的 贡献 。 但 是 当时 Elasticsearch 还 没有 官方 python 客户 端 ， 所 以 监控 程序 都 是 用 
的 是 pyes 库 。 对 于 最 新 版 的 ES 来 说 ， 已 经 不 推荐 使 用 了 。 


peek TEJ elasticsearch.py #44744 ° GitHub 地 址 
: https://github.com/Wprosdocimo/Elasticsearch-zabbix ° 


1. ESzabbix.py 
2. ESzabbix.userparm 
3. ESzabbix templates.xml 


其 中 ， 前 两 个 文件 需要 el ES 节点 上 。 如 果 节 点 上 运行 的 是 yum 安装 的 
zabbix， 二 者 的 默认 位 置 应 该 分 别 是 : 


1. /etc/zabbix/zabbix externalscripts/ESzabbix.py 


2. /etc/zabbix/agent include/ESzabbix.userparm 


然后 在 各 节点 安装 运行 ESzabbix.py Pf $ $9 python # 4&3. : 


# yum install -y python-pbr python-pip python-urllib3 python-uni 
ttest2 
# pip install elasticsearch 


安装 成 功 后 ， 你 可 以 试 运行 下 面 这 行 命令 ， 看 看 命令 输出 是 否 正常 : 


# /etc/zabbix/zabbix_externalscripts/ESzabbix.py cluster status 


es zabbix server 上 的 模板 文件 ， 不 过 在 导入 模板 之 前 ， 还 需要 先 创 
一 个 数值 映射 ， 因 为 在 模板 中 ， 设 置 了 集群 状态 的 触发 报警 ， 没 有 映射 的 话 ， 报 
ae O, Ts 2 数字 不 是 很 易 懂 9 


创建 数值 映射 ， 在 浏览 器 登录 zabbix-web > X: € f£ 8j Zabbix Administration 中 
选择 General 子 菜单 ， 然 后 在 右 侧 下 拉 框 中 点 击 Value Maping ° 


选择 create ^ MARE PIS 


name: ES Cluster State 
0 2 Green 1 = Yellow 2 = Red 


完成 以 后 ， 即 可 在 Templates 页 中 通过 import 功能 完成 导入 
ESzabbix_templates.xml ° 


在 给 ES 各 节点 应 用 新 模板 之 前 ， 需 要 给 每 个 节点 定义 一 个 ($NODENAME) 宏 ， 具 
体 值 为 该 节点 elasticsearch.yml 中 的 node.name 值 。 从 统一 配 管 的 角度 ， 
建议 大 家 都 设置 为 ip 地 址 。 


模板 应 用 


导入 完成 后 ，zabbix 里 多 出 来 三 个 可 用 模板 : 


1. Elasticsearch Node & Cache 其 中 包括 两 个 Application : ES Cache 和 ES 
Node。 分 别 有 Node Field Cache Size, Node Filter Cache Size 和 Node 
Storage Size, Records indexed per second 共计 4 个 item 监控 项 。 在 完成 上 
面 说 的 宏 定 义 后 ， 就 可 以 把 这 个 模板 应 用 到 各 节点 ( 即 监控 主机 ) 上 了 © 

2. Elasticsearch Service 只 有 一 个 监控 项 Elasticsearch service status， 做 进程 
监控 的 ， 也 应 用 到 各 节点 上 。 

3. Elasticsearch Cluster 包括 11 个 监控 项 ， 如 下 列 所 示 。 其 中 ，ElasticSearch 
Cluster Status 这 个 监控 项 连带 有 报警 的 触发 器 ， 并 对 应 之 前 创建 的 那个 
Value Map ° 

o Cluster-wide records indexed per second 
o Cluster-wide storage size 

o ElasticSearch Cluster Status 

o Number of active primary shards 


o Number of active shards 

o Number of data nodes 

o Number of initializing shards 

o Number of nodes 

o Number of relocating shards 

o Number of unassigned shards 

o Total number of records 这 个 模板 下 都 是 集群 总 体 情 况 的 监控 项 ， 所 以 ， 
运用 在 一 台 有 ES 集群 读 取 权 限 的 主机 上 即 可 ， 比 如 zabbix server 。 


其 他 


untergeek 最 近 刚 更 新 了 他 的 仓库 ， 重 构 了 一 个 es stats zabbix 模块 用 于 Zabbix 
监控 ， 有 兴趣 的 读者 可 以 参考 : https://github.com/untergeek/zabbix-grab- 
bag/blob/master/Elasticsearch/es_stats_zabbix.README.md 


Elasticsearch 在 运 维 领 域 的 其 他 运用 


目前 Elasticsearch 虽然 以 Elastic Stack 作为 主打 产品 ， 但 其 优秀 的 分 布 式 设 计 ， 
灵活 的 搜索 评分 函数 和 强大 简洁 的 检索 聚合 功能 ， 在 运 维 领域 也 衍生 出 不 少 其 他 有 
趣 的 应 用 方式 。 

对 于 Elastic 公司 来 说 ， 这 些 周边 应 用 ， 也 随时 可 能 成 为 他 们 的 后 续 目标 产品 。 就 
在 本 书 第 一 版 编写 期 间 ，packetbeat 就 被 Elastic 公司 收购 ， 并 且 可 能 作为 未 来 数 
据 采 集 端的 标准 应 用 。 所 以 ，Elastic Stack 用 户 提前 了 解 其 他 方面 的 多 种 可 能 ， 也 
是 非常 有 意义 的 。 


percolator 接口 


在 运 维 体系 中 ， 监 控 和 报警 总 是 成 双 成 对 的 出 现 。Elastic Stack 在 时 序 统计 方面 的 
便捷 ， 在 很 多 时 候 被 作为 监控 的 一 种 方式 在 使 用 。 那 么 ， 自 然 就 引申 出 一 个 问题 : 
Elastic Stack 如 何 做 报警 ? 


对 于 简单 而 且 固定 需求 的 模式 ， 我 们 可 以 在 Logstash 中 利用 filter/metric 和 
filter/ruby 等 插件 做 预 处 理 ， 直 接 output/nagios 3X output/zabbix 来 
报警 ; 但 是 对 于 针对 全 局 的 、 更 复杂 的 情况 ，Logstash 就 无 能 为 力 了 。 


目前 比较 通行 的 办 法 。 有 两 种 : 


.对 于 匹配 报警 ， 采 用 ES 的 Percolator 接口 做 响应 报警 ; 
.对 于 时 序 统计 ， 采 用 定时 任务 方式 ， 发 送 ES aggs 请 求 ， 分 析 响 应 体 报警 。 


针对 报警 的 需求 ， 官方 也 在 最 近 开 发 了 Watcher 商业 产品 ， 和 Shield 一 样 以 
ES 插件 形式 存在 。 = 即 稍微 描述 一 下 Percolator 接口 的 用 法 和 Watcher 产品 的 
思路 。 相 信 稍 有 编程 能 力 的 读者 都 可 以 根据 自己 的 需求 写 出 来 类 似 的 程序 。 


Percolator 接口 


Percolator 接口 和 我 们 习惯 的 搜索 接口 正好 相反 ， 它 要 求 预先 定义 好 query’ AG 
通过 接口 提交 文档 看 能 匹配 上 哪个 query。 也 就 是 说 ， 这 是 一 个 实时 的 模式 过 滤 接 
Do 


5.0 版 中 ， 对 Percolator 功能 做 了 大 幅度 改造 ， 现 在 已 经 没有 单独 的 接口 ， 而 是 作 
为 一 种 mapping 类 型 存在 。 也 就 是 说 ， 我 们 在 创建 索引 的 时 候 需 要 预先 定义 。 


比如 我 们 通过 syslog 来 发 现 硬 件 报错 的 时 候 ， 需 要 预先 定义 mapping : 


# curl -XPUT http://127.0.0.1:9200/syslog -d '{ 


"mappings" { 
"syslog" : { 
"properties" 
"message" 
"type" 
tr 
"severity" 
"type" 
3 
"program" 
"type" 
} 
} 
tr 
"queries" : { 
"properties" 
"query" 
"type" 
} 
} 
} 
} 


} 1 


然后 我 们 往 syslog/queries 里 注册 2 条 percolator 请 求 规则 : 


t 


du 


"text n 


t 
"long" 


oat 


"keyword" 


x 


{ 


"percolator" 


# curl -XPUT http://127.0.0.1:9200/syslog/queries/memory -d '{ 
"query" : { 
"query string" : ( 


"default field" : "message", 
"default operator" : "OR", 
"query" : "mem DMA segfault page allocation AND seve 
rity:>2 AND program:kernel" 
j 
} 
y 
# curl -XPUT http://127.0.0.1:9200/syslog/queries/disk -d '{ 
"query" : { 
"query_string" : { 
"default_field" : "message", 
"default_operator" : "OR", 
"query" : "scsi sata hdd sda AND severity:>2 AND pro 
gram:kernel" 
} 
} 
r' 


然后 ， 将 标准 的 数据 写 入 请 求 做 一 点 改动 ， 通 过 搜索 接口 进行 : 


# curl -XPOST http://127.0.0.1:9200/syslog/_search -d '( 


"query" : ( 
"percolate" : { 
"field" : "query", 
"document type" : "syslog", 
"document" : { 
"program" : "kernel", 
"severity" : 3, 
"message" : "swapper/0: page allocation failure: 
order:4, mode:0x4020" 
} 
} 
} 


} 1 


得 到 如 下 结果 : 


{ 
egal = I 
{ 
"n index": "syslog", 
" type": "queries", 
"w ig” D "memory", 
} 
] 
} 


从 结果 可 以 看 出 来 ， 这 条 syslog 日 志 匹 配 上 了 memory 异常 。 接 下 来 就 可 以 发 送 
给 报警 系统 了 。 

如 果 是 syslog 索引 中 已 经 有 的 数据 ， 也 可 以 重新 过 一 遍 Percolator 查询 。 比 如 我 
们 有 一 条 之 前 已 经 写 入 到 http://127.0.0.1:9200/syslog/cisco/1234567 的 
数据 ， 如 下 命令 就 可 以 把 这 条 数据 再 过 一 次 percolate : 


# curl -XPOST http://127.0.0.1:9200/syslog/_search -d '( 


"query" : { 
"percolate" : { 
"field" : "query", 
"document type" : "syslog", 
"index" : "syslog", 
"type" : "cisco", 
Pad? 234560747 
} 
} 


} 1 


利用 更 复杂 的 query DSL 做 Percolator 请 求 的 示例 ， 推 荐 阅读 官网 这 篇 geo 定位 
的 文章 : https://www.elastic.co/blog/using-percolator-geo-tagging 


Watcher 产品 


Watcher 也 是 Elastic.co 公司 的 商业 产品 ， 和 Shield > Marvel 一 样 插件 式 安装 即 
"p: 


bin/plugin -i elasticsearch/license/latest 
bin/plugin -i elasticsearch/watcher/latest 


Watcher 使 用 方面 ， 也 提供 标准 的 RESTful 接口 ， 示 例如 下 : 


# curl -XPUT http://127.0.0.1:9200/_watcher/watch/error_status - 
d 1 


{ 
"trigger": { 
ESchedule™ eos cronc Ob seca 2 
ty 
"input" : { 
"search" : { 
"request" : { 
"indices" : [ "<logstash-{now/d}>", "«logstash-( 
now/d-1dj»" ], 
"body" : { 
"query" : { 


"filtered" : { 
atery naccnan Status 
error" }}, 
"filter" : { "range" : { "@timestamp 


" : { "from" : "now-5m" }}} 
} 
} 
} 
} 
} 
ty 
"condition" : { 


"compare" : { "ctx.payload.hits.total" : { "gt" : © }} 
ty 


"transform" : { 


"search" : { 
"request" : ( 
"indices" : [ "<logstash-{now/d}>", "«logstash-( 
now/d-1dj»" ], 
"body" : { 
"query" : { 


"filtered" : { 
"query" : { "match" : { "status" : " 
error" }}, 
"filter" : { "range" : { "@timestamp 
" : { "from" : "now-5m" }}} 
} 
tr 
"aggs" : { 
OMIM | e N 
"terms" : { 
"field" : "userid" 


3 
"actions" : { 
"email_admin" : { 
"throttle period" : "15m", 
"email" : { 
"to" : "admin@domain", 
"subject" : "Found {{ctx.payload.hits.total}} Er 
ror Events at {{ctx.trigger.triggered_time}}", 
"priority" : "high", 
"body" : "Top10 users:\n{{#ctx.payload.aggregati 
ons.topn.buckets}}\t{{key}} {{doc_count}}\n{{/ctx.payload.aggreg 
ations.topn.buckets}}" 


} 


上 面 这 行 命令 ， 意 即 : 


5 分 钟 ， 向 最 近 两 天 的 logstash-yyyy.MM.dd 索引 发 起 一 次 条 件 为 最 近 

aye > status 字段 内 容 为 error 的 查询 请 求 ; 

2. 对 查询 结果 做 hits 总 数 大 于 0 的 判断 ; 

3. 如 果 为 真 ， 再 请 求 一 次 上 述 条 件 下 ，Uuserid 字段 的 Top 10 数据 集 作 为 后 续 处 
理 的 来 源 ; 

4. 如 果 最 近 15 分 钟 内 未 发 送 过 报警 ， 则 向 admin@domain 邮箱 发 送 一 个 标题 
A "Found N erroneous events at yyyy-MM-ddTHH:mm:ssZ"， 内 容 为 "Top10 
users" 列表 的 报警 邮件 。 


整个 请 求 体 顺序 执行 。 目 前 trigger 只 支持 scheduler 方式 (但 是 Schedule 下 有 
crontab ` interval ` hourly » daily » weekly ` monthly ` yearly 等 多 种 写法 )，input 
支持 search 和 http 7 X > actions 支持 email > logging > webhook 7 X * 
transform 是 可 选项 ， 而 且 可 以 设置 在 actions €. > *F actions 做 不 同 的 payload 
转换 。 


crontab 定义 语法 和 Linux 标准 不 太一 致 ， 采 用 的 是 Quartz， 文 件 
见 : http://www.quartz-scheduler.org/documentation/quartz- 
1.x/tutorials/crontrigger ° 


condition, transform 和 actions 中 ， 默 认 使 用 Watcher 增强 版 的 xmustache 模板 
语言 (示例 中 的 数组 循环 就 是 一 例 ) 。 也 可 以 使 用 固化 的 脚本 文件 ， 比 如 有 
threshold_hits.groovy 的 话 ， 可 以 执行 : 


"condition" : ( 
ESC hal cn 
"file" : "threshold_hits", 
"params" : ( 
"threshold" : 0 
} 
} 
} 


Watcher 中 可 用 的 ctx 变量 包括 : 


e Cctx.watch id 


e ctx.execution time 


watcherdk £& 


e ctx.trigger.triggered_time 
e ctx.trigger.scheduled time 
e ctx.metadata.* 


e ctx.payload.* 


完整 的 Watcher 插件 内 部 执行 流程 如 下 图 。 相 信 有 编程 能 力 的 读者 都 可 以 用 
crontab/at 配合 curl » email 工具 仿造 出 来 类 似 功 能 的 shell 脚本 。 





Watch 
Triggered 


check condition 
condition 
met? 


for each action for each action 


cap 


yes no 
transform 
payload 















yes no 


exec action 
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在 search ¥ > xt indices 内 容 可 以 写 完 整 的 索引 名 比如 syslog ， 也 可 以 写 通 配 
符 比 如 logstash-* ， 也 可 以 写 时 序 索 引 动态 定义 方式 如 «logstash- 
(now/d)» 。 而 这 个 动态 定义 ，Watcher 是 支持 根据 时 区 来 确定 的 ， 这 个 需要 在 
elasticsearch.yml 里 配置 一 行 : 


watcher.input.search.dynamic indices.time zone: '+08:00' 


笔者 仿照 watcher 的 配置 语法 ， 开 源 了 一 个 基于 Kibana 扩展 的 类 watcher 监控 项 
目 ， 本 书 稍 后 Kibana 章节 将 会 有 详细 介绍 。 


ElastAlert 


ElastAlert 是 Yelp 公司 开源 的 一 套用 Python2.6 写 的 报警 框架 。 属 于 后 来 
Elastic.co 公司 出 品 的 Watcher 同类 产品 。 官 网 地 址 
见 : http://elastalert.readthedocs.org/ ° 


安装 


比 官网 文档 说 的 步骤 稍微 复杂 一 点 ， 因 为 其 中 mock 模块 安装 时 依赖 的 setuptools 
要 求 版 本 在 0.17 以 上 ，CentOS6 默认 的 不 够 ， 需 要 通过 yum 命令 升级 ， 当 前 可 以 
升级 到 的 是 0.18 版 。 


# yum install python-setuptools 

# git clone https://github.com/Yelp/elastalert.git 
# cd elastalert 

# python setup.py install 

# cp config.yaml.example config. yaml 


安装 完成 后 会 自 带 三 个 命令 : 


e elastalert-create-index ElastAlert 会 把 执行 记录 存放 到 一 个 ES 索引 中 ， 该 命 

令 就 是 用 来 创建 这 个 索引 的 ， 默 认 情 况 下 ， 索 引 名 叫 
elastalert status 。 其 中 有 4 个 _type， 都 有 自己 的 @timestamp + 
段 ， 所 以 同样 也 可 以 用 kibana 来 查看 这 个 索引 的 日 志 记 录 情 况 。 

e elastalert-rule-from-kibana 从 Kibana3 已 保存 的 仪表 瘟 中 读 取 Filtering 设置 ， 
帮助 生成 config.yaml 里 的 配置 。 不 过 注意 ， 它 只 会 读 取 filtering， 不 包括 
queries ° 

e elastalert-test-rule 测试 自 定义 配置 中 的 rule 设置 。 


# python -m elastalert.elastalert --config ./config.yaml 


或 者 单独 执行 rules folder 里 的 某 个 rule : 


# python -m elastalert.elastalert --config ./config.yaml --rule 
./examele_rules/one_rule.yaml 


结构 


dic doce M 0 几 个 部 分 ， 但 
是 它 有 自己 的 命名 。 


query 部 分 
除了 有 关 ES 服务 器 的 配置 以 外 ， 主 要 包括: 


e run every 配置 ， 用 来 设置 定时 向 ES 发 请 求 ， 默 认 5 分钟。 

e buffer time 配置 ， 用 来 设置 请 求 里 时 间 字 段 的 范围 ， 上 默认 45 分 钟 。 

e rules folder 配置 ， 用 来 加 载 下 一 阶段 的 rule 设置 ， 默 认 是 
example_rules ° 

e timestamp field 配置 ， 设 置 buffer time 时 针对 哪个 字段 ， 默 认 是 
@timestamp ° 

e timestamp type 配置 ， 设 置 timestamp field 的 时 间 类 型 ，ElastAlert 
内 部 也 需要 转换 成 时 间 对 象 ， 默 认 是 IS08601 ， 也 可 以 是 UNIX ° 


rule 部 分 


rule 设置 各 自 独 立 以 文件 方式 存储 在 ”rules folder 设置 的 目录 里 。 其 中 可 以 定 
义 下 面 这 些 参数 : 


e name 配置 ， 每 个 rule 需要 有 自己 独立 的 name， 一 旦 重复 ， 进 程 将 无 法 局 
动 。 

e type 配置 ， 选 择 某 一 种 数据 验证 方式 。 

e index 配置 ， 从 某 类 索引 里 读 取 数 据 ， 目 前 已 经 支持 Ymd 格 式 ， 需 要 先 设置 
use strftime index: true， 然 后 匹配 索引 ， 配 置 形 如 : index: logstash-es-test- 
%Y9%m.%d， 表 示 匹 配 logstash-es-test 名 称 开 头 ， 以 年 月 日 作为 索引 后 组 的 
index » 

e filter 配置 ， 设 置 向 ES 请 求 的 过 滤 条 件 。 

e timeframe 配置 ， 累 积 触发 报警 的 时 长 。 


e alert 配置 ， 设 置 触 发 报警 时 执行 哪些 报警 手段 。 
不 同 的 type 还 有 自己 独特 的 配置 选项 。 目 前 ElastAlert 有 以 下 几 种 自 带 ruletype : 


e any : 只 要 有 匹配 就 报警 ; 

e blacklist : compare_key 字段 的 内 容 匹 配 上 blacklist 数组 里 任意 内 

X ; 

whitelist : compare key 字段 的 内 容 一 个 都 没 能 匹配 上 whitelist 数 

组 里 内 容 ; 

e change :在 相同 query key 条 件 下 ， compare key 字段 的 内 容 ， 在 
timeframe 范围 内 发 送 变 化 ; 

e frequency : pue query key 条 件 下 ， timeframe 范围 内 有 
num events 个 被 过 滤 出 来 的 异常 

e spike :在 相同 query_key Soy 后 两 个 timeframe 范围 内 数据 量 
相差 比例 超过 spike height ° 2 通过 spike type 设置 具体 涨 跌 
方向 是 up, down, both 。 还 可 以 通过 threshold ref 设置 要 求 上 一 个 
周期 数据 量 的 下 限 ， threshold cur 设置 要 求 当 前 周期 数据 量 的 下 限 ， 如 果 
数据 量 不 到 下 限 ， 也 不 触发 ; 

e flatline : timeframe 范围 内 ， 数 据 量 小 于 threshold Wa; 

e new term : fields 字段 新 出 现 之 前 terms window size (默认 30 X) 
范围 内 最 多 的 terms size (默认 50) 个 结果 以 外 的 数据 ; 

e cardinality :在 相同 query key 条 件 下 ， timeframe 范围 内 
cardinality field 的 值 超过 max_cardinality 或 者 低 于 


min_cardinality ° 


alert 部 分 


alert 配置 是 一 个 数组 ， 目 前 支持 command, email > jira > opsgenie > sns ° 
hipchat > slack 等 方式 。 


e command 


command 最 灵活 也 最 简单 。 默 认 会 采用 %(fieldname)s 格式 : 


command: ["/bin/send alert", "--username", "%(username)s", "--ti 
me", "9?;(key as string)s"] 


如 果 要 用 的 比较 多 ， 可 以 开启 pipe match json 参数 ， 会 把 整个 过 滤 到 的 内 
容 ， 以 一 整个 JSON 字符 串 的 方式 管道 输入 指定 脚本 。 


e email 


email 方式 采用 SMTP 协议 ， 所 以 有 一 系列 smtp * 配置 ， 然 后 加 上 email 参 
数 提 供 收 件 人 地 址 数组 。 


特殊 的 是 ，email 和 jira 两 种 方式 ，ElastAlert 提供 了 一 些 内 容 格式 化 模板 : 


比如 可 以 这 样 控制 邮件 标题 : 


alert_subject: "Issue {0} occurred at {1}" 
alert_subject_args: 

- issue.name 

- "@timestamp" 


而 默认 的 邮件 内 容 模板 是 : 


body = rule_name 
[alert text] 
ruletype text 
(top counts) 
(field values) 


这 些 内 容 同样 可 以 通过 alert text (及 对 应 alert text args ) 等 来 灵活 修 
改 。 


此 外 ，alert 还 有 一 系列 控制 报警 风暴 的 选项 ， 从 属于 rule: 


e aggregation : 设置 一 个 时 长 ， 则 该 时 长 内 所 有 报警 最 终 合 在 一 起 发 一 次 ; 
e realert :设置 一 个 时 长 ， 则 该 时 长 内 ， 相 同 query key 的 报警 只 发 一 

EE 

e exponential realert : 设置 一 个 时 长 ， 必 须 大 于 realert 设置 。 则 在 
realert 到 exponential realert 之 间 ， 每 次 报警 后 ,realert 自动 翻 


fà o 


微 信 告 警 插件 


社区 有 人 提供 了 使 用 微 信 做 ElastAlert 告警 操作 的 扩展 ， 其 GitHub 地 址 
JL : https://github.com/anjia0532/elastalert-wechat-plugin ° 


enhancements 部 分 


match enhancements 配置 ， 设 置 一 个 数组 ， 在 报警 内 容 发 送 到 alert 之 前 修改 
具体 数据 。ElastAlert 默认 不 提供 具体 的 enhancements 实现 ， 需 要 自己 扩展 。 


不 过 ， 作 为 通用 方式 ，ElastAlert 提供 几 个 便捷 选项 ， 把 Kibana 地 址 加 入 报警 : 


e generate kibana link : 自动 生成 一 个 Kibana3 的 临时 仪表 盘 附 在 报警 内 
容 上 。 

e use kibana dashboard : 采用 现成 的 Kibana3 仪表 盘 附 在 报警 内 容 上 。 

e use kibana4 dashboard :采用 现成 的 Kibana4 仪表 盘 附 在 报警 内 容 上 。 


扩展 
rule 


创建 一 个 自己 的 rule， 是 以 Python 模块 的 形式 存在 的 ， 所 以 首先 创建 目录 : 


# mkdir rule_modules 
# cd rule modules 
# touch init .py example rule.py 


example rule.py 的 内 容 如 下 : 


import dateutil.parser 
from elastalert.util import ts_to_dt 
from elastalert.ruletypes import RuleType 


class AwesomeNewRule(RuleType): 
# 用 来 指定 本 rule 对 应 的 配置 文件 中 必要 的 参数 项 
required options = set(['time start', 'time end', 'usernames 
']) 
# 每 次 运行 获取 的 数据 以 时 间 排 序数 据 传递 给 add data HA 
def add_data(self, data): 
for document in data: 
# 配置 文件 中 的 设置 可 以 通过 self.rule[] 获取 
if document['username'] in self.rule['usernames']: 
login time - document['Qtimestamp'].time() 
time start - dateutil.parser.parse(self.rule['ti 
me start']).time() 
time end - dateutil.parser.parse(self.rule['time 
.end']).time() 
if login time » time start and login time « time 
.end: 
# RANRAR > self.add match 添加 
self.add match(document) 


4 alert text 中 使 用 的 文本 
def get_match_str(self, match): 
return "%s logged in between %s and %s" 96 (match['userna 
me'], 
self.rule['ti 
me start'], 
self.rule['ti 


me end']) 
def garbage collect(self, timestamp): 
pass 


type: rule_modules.example_rule.AwesomeRule 
time_start: "20:00" 
time_end: "24:00" 
usernames: 
- "admin" 
- "USerXYZ" 
- "foobaz" 


即 可 使 用 。 


alerter 


alerter 也 是 以 Python 模块 的 形式 存在 的 ， 所 以 还 是 要 创建 目录 (如 果 之 前 二 次 开发 
rule 已 经 创建 过 可 以 跳 过 ) : 


# mkdir rule_modules 
# cd rule_modules 
# touch _ init__.py example alert.py 


example alert.py 的 内 容 如 下 : 


from elastalert.alerts import Alerter, basic_match_string 


class AwesomeNewAlerter(Alerter): 
required options = set(['output file path']) 
def alert(self, matches): 
for match in matches: 
with open(self.rule['output file path'], "a") as out 


put file: 

4 basic match string 函数 用 来 转换 异常 数据 成 默认 格式 的 
TA 

match string - basic match string(self.rule, mat 
ch) 


output file.write(match string) 
# 报警 发 出 后 ，ElastAlert 会 调用 该 函数 的 结果 写 入 ES 索引 的 alert inf 
o 字段 内 
def get_info(self): 
return {'type': 'Awesome Alerter', 
'output file': self.rule['output_file_path']} 


alert: "rule modules.example alert.AwesomeNewAlerter" 
output file path: "/tmp/alerts.log" 


即 可 使 用 。 


enhancement 


enhancement 也 是 以 Python 模块 的 形式 存在 的 ， 所 以 还 是 要 创建 目录 (如 果 之 前 二 
次 开发 rule 或 alert 已 经 创建 过 可 以 跳 过 ) : 


# mkdir rule_modules 
# cd rule_modules 
# touch init .py example enhancement. py 


example enhancement.py 的 内 容 如 下 : 


from elastalert.enhancements import BaseEnhancement 
class MyEnhancement(BaseEnhancement ) : 
def process(self, match): 
if 'domain' in match: 
url = "http://who.is/whois/%s" 96 (match['domain']) 
match['domain whois link'] = url 


在 需要 的 rule 配置 文件 中 添加 如 下 内 容 即 可 局 用 : 


match_enhancements : 
- "rule modules.example enhancement.MyEnhancement" 


因为 match enhancements 是 个 数组 ， 也 就 是 说 ， 如 果 数 组 有 多 个 
enhancement， 会 依次 执行 ， 完 全 完成 后 ， 才 传递 给 alert 。 


DELETE 


之 前 已 经 介绍 过 ，ES 默认 存储 数据 时 ， 是 有 索引 数据 、_all 全 文 索引 数 

IÆ ^ source JSON 字符 串 三 份 的 。 其 中 ， 索 引 数 据 由 于 倒 排 索引 的 结构 ， 压 缩 比 
非常 高 。 因 此 ， 在 某 些 特定 环境 和 需求 下 ， 可 以 只 保留 索引 数据 ， 以 极 小 的 容量 代 
价 ， 换 取 ES 灵活 的 数据 结构 和 有 聚合 统计 功能 。 


在 监控 系统 中 ， 对 监控 项 和 监控 数据 的 设计 一 般 是 这 样 : 


metric path value timestamp (Graphite 设计 ) { "host": "Host name 1", "key": 
"item key", "value": "33", "clock": 1381482894 } (Zabbix 设计 ) 


这 些 设计 有 个 共同 点 ， 数 据 是 二 维 平面 的 。 以 最 简单 的 访问 请 求 状态 监控 为 例 ， 一 
次 请 求 ， 可 能 转换 出 来 的 metric path 或 者 说 key 就 

有 : {city,isp,host,upstream}.{urlpath...}.{status,rt,ut,size,speed} 这 么 多 种 。 
假设 urlpath 有 1000 个 ， 就 是 20000 个 组 合 。 意 味 着 需要 发 送 20000 条 数据 ， 做 
20000 次 存储 。 


而 在 ES 里 ， 这 就 是 实 实在 在 1000 条 日 志 。 而 且 在 多 
相对 固定 ， 压 缩 比 还 会 更 高 。 所 以 ， 使 用 ES 来 做 时 序 
完全 可 行 的 办 法 。 


条 日 志 的 时 候 ， 因 为 词 元 的 
监控 数据 的 存储 和 查询 ， 是 


对 时 序数 据 ， 关 键 就 是 定义 缩减 数据 重复 。template 示例 如 下 : 


"order" = 2; 
"template" : "logstash-monit-*", 
"settings" : { 
tr 
"mappings" : { 
" default " : { 
"source" : T 
"enabled" : false 
i 
Hall" =f 
"enabled" : false 
} 
} 
ty 
"aliases" : { } 
} 


如 果 有 些 字 段 ， 是 完全 不 用 Query ， 只 参加 Aggregation 的 ， 还 可 以 设置 : 


"properties" : { 
"eds o 
"index" : "no", 
"type" : "keyword" 
} 
}, 


X T Elasticsearch 用 作 rrd 用 途 ， 与 MongoDB 等 其 他 工具 的 性 能 测试 与 对 比 ， 可 
以 阅读 腾讯 工程 师 写 的 系列 文章 : http://segmentfault.com/a/1190000002690600 


Grafana 


Grafana 是 一 个 开源 的 指标 量 监测 和 可 视 化 工具 。 常 用 于 展示 基础 设施 的 时 序数 据 
ae 7 Jf » Grafanaa) dashboard Ak 7 3E 3$ JA BE > 2 xp EIA 7E 4€ 7] 38 16 89 
一 大 利器 。 


官方 在 线 的 demo 可 以 在 这 里 找到 : http://play.grafana.org/ 


grafana 的 套路 基本 上 跟 kibana 差 不 多 ， 都 是 根据 查询 条 件 设 置 聚 合 规 则 ， 在 合适 的 
图 表 上 进行 展示 ， 多 个 图 表 共 同 组 建成 一 个 dashboard， 就 悉 kibana 的 用 户 应 该 可 

以 非常 容易 上 手 。 另 外 grafana 的 可 视 化 功能 比 kibana 强 得 多 ， 后 面 逐 步 会 介绍 到 ， 
而 且 4 以 上 版 本 将 集成 报警 功能 。 


$9 器 Nginx dashboard ~ 


$$ Detail-Server $$ New dashboard ”器 Postgesqi-Dashbord ”器 Servers-Overview 


nginx 流 量变 化 趋势 /总 流量 访问 压力 


nginx 状 态 码 统计 PVIIP 统 计 (已 排除 蜂 蛛 ) 





安装 


Grafana 的 安装 非常 简单 ， 官 方 就 有 软件 仓库 可 以 直接 使 用 ， 也 可 以 通过 docker 镜 
像 等 方式 直接 本 地 启动 。 
参考 官方 文档 的 安装 方法 ， 对 应 找到 你 的 操作 系统 的 安装 方法 即 可 : 
http://docs.grafana.org/ 
值得 一 提 的 是 ， 由 于 官方 仓库 托管 在 S3 上 ， 国 内 用 户 直 接 访问 苦 不 堪 言 ， 万 幸 
的 是 清华 大 学 tuna 镜 像 站 已 经 提供 了 grafana 的 镜像 ， 只 需要 将 官方 文档 中 提 到 
的 仓库 地 址 对 应 的 换 成 清华 大 学 的 镜像 站 的 地 址 即 可 : 
https://mirrors.tuna.tsinghua.edu.cn/grafana/ 


> Jt 


安装 完毕 后 ， 使 用 service grafana-server start 就 可 以 启动 grafana， 访 
问 http://your-host:3000 就 可 以 看 到 登录 界面 了 。 
默认 的 用 户 名 和 密码 都 是 admin 。 


默认 情况 下 ，grafana 的 配置 存储 于 sqlite3 中 ， 如 果 你 想 使 用 其 他 存储 后 
端 ， 如 mysql ， postgresql 等 ， 请 参考 官方 文档 配置 : 
http://docs.grafana.org/installation/configuration/ 


grafana 的 几 个 基本 构成 和 基本 概念 参考 官方 文档 : 


配置 数据 产 


先 要 明确 一 点 ，grafana 只 是 一 个 dashboard(4 版 本 开始 将 引入 报警 功能 )， 负 责 把 数 
据 库 中 的 数据 进行 可 视 化 展示 ， 本 身 并 不 存储 任何 数据 ， 另 外 某 些 查询 和 聚合 使 用 
的 是 数据 库 本 身 提供 的 功能 ， 需 要 对 应 的 数据 库 去 支持 。 因 此 不 代表 你 换 了 一 个 数 
据 库 后 端 就 一 定 能 展示 相同 的 图 形 。 


grafana 目 前 支持 的 时 序数 据 库 有 : Graphite, Prometheus, Elasticsearch, InfluxDB, 
OpenTSDB, AWS Cloudwatch。 未 来 可 能 会 有 更 多 的 数据 库 的 支持 加 入 ， 请 关注 
更 新 。 也 可 以 使 用 第 三 方 插件 引入 支持 。 


我 们 这 里 使 用 Elasticsearch 作为 数据 库 的 来 源 。 


首先 进入 数据 源 的 设置 页 面 ， 点 击 左 上 和 角 的 图 标 ， 选 择 Data Sources - Add 


data sources : 


Data So 


admin 
[ eva Ja 


Dashboards 
Data Sources 
Plugins 
Admin 


Pin 


Data Sources + Add data source 


进入 数据 源 的 设置 ， 例 如 我 们 要 从 logstash-YYYY.MM.DD 2% index T ix: X ak 
据 ， 就 像 kibana 默 认 的 index 那 样 ， 像 这 样 配 置 即 可 : 





Edit data source 


logstash Default C 


数据 源 选 ElasticSearch 


Http settings 


http://localhost:9200 


‘py O > 这 里 注意 ， 如 果 你 的 ES 不 
对 外 暴露 ， 选 proxy， 上 


面 的 Url 选择 方向 代理 的 后 
端 。 否 则 选 direct，Url 填 
入 你 能 访问 到 的 ES 地 址 


Http Auth Basic Auth With Credentials 


Elasticsearch de 


ndex name [logstash-] Y Y Y Y.MM.DD Pattern 


Time field name @timestamp 这 里 照 着 Kibana 的 配置 抄 就 可 以 了 
如 果 你 要 用 别 的 index， 这 里 就 照 


版 本 要 选 对 ，3.1.1 版 本 只 支持 到 2.Xx， 未 来 版 本 将 会 支持 5.0 


Default query settings 


Group by time interval 





生成 第 一 个 图 表 


数据 源 配 置 好 之 后 ， 就 可 以 开始 我 们 可 视 化 的 第 一 步 了 。 这 一 步 相 对 较为 简单 ， 只 
$ # BES #4) query-string-syntax( 
https://www.elastic.co/guide/en/elasticsearch/reference/5.0/query-dsl-query-string- 
query.html#query-string-syntax ) 就 可 以 轻松 写 出 来 。 


想 创 建 图 表 ， 首 先 得 有 dashboard ，new 一 个 dashboard 出 来 ， 就 可 以 尽情 的 开 
T: 


A 
%5 - Z4 Home - a 


admin 


DevOps 


Dashboards Home 


NSS 
SQ 


Playlists 


Data Sources Snapshots 


ia 
| 

i ] 
LAR. 


! + 
Plugins New 


=. Import 


Admin 


Pin 





比如 我 现在 通过 collectd 收集 上 来 了 cpu 占 用 比 的 数据 ， 硕 望 绘制 成 CPU 曲线 ， 
很 明显 我 们 需要 创建 一 个 折线 图 ， 那 么 在 dashboard 上 new 一 个 折线 图 的 panel 即 
可 (graph): 


= 25 - 
49 New dashboard - = 


Collapse row 
Add Panel Dashboard list 


Set height Pie Chart 
Move Graph 


Row editor Plugin list 


Delete row Singlestat 


Table 


Text 





先 在 kibana 中 看 看 查询 结果 





Discover Visualize Dashboard Settings © Last 15 minutes 
afana D 同 的 语 ; : 
type:collectd AND plugin:cpu AND collectd type:percent  «imm————— — grafana 使 用 的 和 kibana 相 同 的 语法 It] =) G 
logstash-* 4,309 hits 
Selected Fields November 27th 2016, 23:49:59.911 - November 28th 2016, 00:04:59.911 — by 30 seconds 
host < 
value 


type_instance 

plugin 

collectd_type 
Available Fields 


@timestamp 


@version 
Time collectd_type host plugin type_instance value 

id 
index » November 28th 2016, 00:04:53.373 percent 1 cpu user 42.454 
-score » November 28th 2016, 00:04:53.373 percent cpu nice 2.618 
-ype » November 28th 2016, 00:04:53.373 percent cpu system 5.647 
type 

» November 28th 2016, 00:04:53.373 percent cpu steal 0.205 

» November 28th 2016, 00:04:53.373 percent $ a cpu idle 43.686 

» November 28th 2016, 00:04:53.373 percent f: cpu interrupt 0 

» November 28th 2016, 00:04:53.373 percent cpu wait 4.312 


很 明显 ， value 是 希望 绘制 到 曲线 上 的 点 ， 而 type instance 应 该 作为 ES 有 聚合 
的 bucket ， 如 果 host 有 多 个 ， 那 么 host 也 应 作为 一 个 bucket， 我 们 先 不 管 
这 个 host， 后 面 会 再 说 怎么 按照 host 分 图 形 ，grafana 有 更 巧妙 的 办 法 。 


bucket 的 作用 非常 类 似 于 sql 中 的 GROUP BY ， 于 是 新 建 的 panel 的 查询 应 该 像 这 


22 New dashboard - : Back to dashboard < zoomout > © Last 1 hour 
CPU 变化 曲线 


idle 
interrupt 
nice 
softirq 
steal 


system 
00:15 00:20 


Graph General Metrics Axes Legend Display Time range 


X type:collectd AND plugin:cpu AND collectd_type:percent 
Average value > Options 
Terms type_instance * Bottom 10, Order by: Term value 


Date Histogram timestamp > Interval: 1m 


E Panel data source logstash ~ + Add query 





简单 解释 一 下 这 些 配置 : 


e query: 对 应 的 就 是 kibana 上 面 的 查询 条 件 ， 先 把 想 要 展示 的 数据 全 部 select 出 
来 ， 然 后 进行 聚合 或 筛选 , Alias 是 给 这 个 查询 起 个 别名 ， 可 用 于 图 例 说 明 

e metric: 这 个 就 是 关键 的 指标 量 的 ， 到 底 展 示 的 是 什么 东西 。 这 里 展示 的 是 
GROUP BY 之 后 对 value 求 平均 值 

e Group by: 对 应 elasticsearch 的 bucket， 按 照 type instance 分 桶 


整个 查询 下 来 大 致 相当 于 SQL 中 的 SELECT avg(value) WHERE 
query string('type:collectd AND plugin:cpu AND 

collectd type:percent') GROUP BY type instance GROUP BY 
Date Histogram(Qtimestamp) 


如 果 只 关心 CPU 的 消耗 ， 不 关心 CPU 的 空闲 (idle)， 布 望 仅仅 把 idle 曲线 隐藏 
掉 ， 也 很 简单 ， 只 要 在 Display 的 选项 卡 中 选择 隐藏 掉 idle 的 line 即 可 ， 瞧 : 


CPU 变化 曲线 


idle 
= interrupt 
nice 
= Softirq 
= steal 


system 
00:00 


Graph General Metrics Axes Legend Display Time range 


Draw Modes Mode Options Hover info Stacking & Null value 


Bars Fill Mode All series ~ Stack 


Lines (v Line Width Sort order None Null value connected ~ 


这 里 可 以 选择 要 覆盖 的 规则 
p 我 们 将 idle 的 Lines 属 性 设置 为 
Re JEF 


的 曲线 中 已 经 不 显示 CPU 空 闪 了 


Points Staircase 


Series specific overrides @ 


X alias or regex idle x Lines: false + 


Add series specific option 





graph 图 表 能 配置 的 项 很 多 ， 包 括 图 例 的 颜色 ， 位 置 ， 显 示 的 值 等 等 ， 其 至 可 以 配 
置 数据 的 单位 ， 以 便于 更 优雅 的 展示 ， 这 里 就 不 一 一 列举 了 。 


把 希望 展示 的 图 表 一 个 个 加 进去 ， 最 终 一 个 完整 的 dashboard 就 生成 了 : 


NS My Ar E JM 


m 
30.61 MiB. 
7.58 MiB. 


ee 
0500 06:00 07:00 0800 09:00 10:00 





这 个 功能 实在 是 grafana 的 一 大 亮点 ， 不 得 不 提 。 模 板 可 以 让 你 轻松 的 批量 生成 同一 
类 型 的 查询 ， 而 不 用 一 个 个 添加 这 些 panel， 实 在 是 生成 动态 可 视 化 图 表 的 大 杀 


比如 现在 要 统计 各 个 网 卡 的 流量 ， 而 服务 器 可 能 包含 多 个 网 

卡 ，1o ，ethg , ethi 等 等 ， 按 照 前 面 的 套路 ， 可 能 会 想到 将 网 卡 名 作为 bucket 

+ 47GROUP BY 操作 。 思 路 没 错 ， 但 是 这 会 导致 所 有 网 卡 的 流量 在 同一 个 图 表 显 

示 ， "ii mE 的 时 候 非常 凌乱 。 再 比如 网 卡 之 间 可 能 流量 根本 不 对 等 ， 某 块 网 卡 的 

流量 高 出 其 他 网 卡 好 几 个 数量 级 ， 这 将 导致 其 他 网 卡 的 流量 曲线 非常 接近 0， 以 至 
AM 楚 流 量变 化 了 8 


2 


Grafana 


因此 需要 将 不 同 的 网 卡 流 量 放 在 不 同 的 panel 分 别 展 示 ， 但 是 不 同 服务 器 的 网 卡 数 
量 可 能 又 不 一 样 ， 因 此 查询 条 件 没 法 写成 一 个 国定 的 ， 需 要 动态 化 。 


先 从 kibana 看 看 网 卡 流量 的 查询 : 









type:collectd AND plugin:interface AND collectd_type:if_octets 





logstash-* 1,610 hits 


Selected Fields November 28th 2016, 10:26:43.566 - November 28th 2016, 10:41:43.566 — by 30 seconds 
Wu < 
mx 
plugin_instance Po 
8 | 
Available Fields a IE | 
Popular 
10:27:00 10:28:00 10:41:00 
a cays @timestamp per 30 seconds 
host "m 
puot Time plugin instance ^ X » rx tx 
@timestamp 
» November 28th 2016, 10:41:41.055 tun® 3,079,992 ,509 3,174,417,132 
@version 
id » November 28th 2016, 10:41:41.055 lo 8,549, 839,692,706 8,549, 839,692,706 
_index » November 28th 2016, 10:41:41.055 ethd 12,610,485 , 608 , 306 13,595,827,871,528 
score 
3 > November 28th 2016, 10:41:40.543 eth@ 266,465,604,346 235,557,943,459 
type 
e » November 28th 2016, 10:41:40.543 tun0 126,506,763 3,749,401 
» November 28th 2016, 10:41:40.543 lo 83,304,835,485 83,304,835,485 
» November 28th 2016, 10:41:39.921 ethd 52,201,569,252 9,646,154,199 
» November 28th 2016, 10:41:39.921 eth1 27,166,509 83,045,235 
» November 28th 2016, 10:41:39.921 1o 69,877,612,021 69,877,612,021 
Maviamhan 22th IMIE 10.41.22 272 nthi 240 943 920 627 225 204 AAA 374 


查询 条 件 为 type:collectd AND plugin:interface AND 

collectd type:if octets ， 可 以 得 到 所 有 网 卡 每 一 时 刻 的 rx , tx 848 o wR 
我 们 要 得 到 每 一 块 网 卡 的 流量 ， 很 明显 要 再 追加 一 个 动态 查询 条 件 AND 
plugin_instance:$interface ， 需 要 提前 对 plugin instance 做 一 

次 distinct ， 拿 出 所 有 可 能 的 值 ， 再 拼接 到 这 个 动态 查询 上 。 这 个 就 是 grafana 
模板 的 基本 使 用 方式 。 


要 想 使 用 模板 ， 首 先 要 先 创建 动 数 的 查询 条 件 ， 在 顶部 点 击 设置 按钮 ， 进 
入 Templating 设置 : 


470 


itd 


Settings 
Annotations 
View JSON 
Save As... 


Delete dashboard 
Temp ating | Variables Edit 


Variable Pao 这 里 就 是 变量 名 ， 不 要 用 中 文 


Name interface Type Query 


Label 网 卡 名 SN Hide 


这 里 填写 你 想 要 看 到 的 别名 


Query Options 
这 里 填写 数据 源 iH 
Data source - Refresh On Dashboard Load 何 时 刷新 


Query {"find": "terms", "field": "plugin instance","query": "plugin:interface"} 查询 语句 ， 不 同 的 数据 库 语法 不 
同 ， 需 要 看 对 应 的 文档 


Regex I^loy 匹配 的 结果 可 以 进一步 用 正则 筛选 ， 这 里 过 滤 掉 了 lo 网 卡 


Selection Options 
Multi-value 是 否 多 选 值 


Include All option [ 必 ， 是 否 包含 人 选项 ， 网 卡 流量 可 以 同时 全 部 展示 ， 因 此 勾 选 上 


Custom all value 


Value groups/tags (Experimental feature) 


Enable 





最 关键 的 地 方 在 Query 这 个 配置 ， 这 里 就 是 定义 怎么 获取 到 $interface 这 个 变 
量 的 所 有 可 选 值 ， 每 个 数据 库 的 语法 不 一 样 ， 比 如 Elasticsearch 的 Template 语 法 在 
这 里 : http://docs.grafana.org/datasources/elasticsearch/#templating ， 如 果 你 使 用 


的 是 其 他 数据 源 ， 那 么 查询 对 应 数据 源 的 模板 语法 即 可 。 


这 个 查询 就 相当 于 在 plugin:interface 这 个 查询 条 件 下 > 
对 plugin instance 这 个 field 进 行 distinct 操 作 ， 结 果 再 使 用 /[ALo]/ 正则 过 
滤 ， 将 lo 这 个 结果 从 结果 集中 排除 掉 。 


结束 后 我 们 就 可 以 看 到 了 这 样 的 单 选 下 拉 框 ; 





引入 了 $interface 这 个 变量 后 ， 我 们 就 可 以 对 查询 条 件 做 下 改进 了 : 


网 卡 etho 的 速率 
300 kBps 
250 kBps 
aoao 2016-11-28 11:17:00.000 
150 kBps b=: 193.6 kBps 


100 kBps 


General Metrics Axes Legend Display Time range 
这 里 引入 了 | 


plugin:interface ANDplugin_instance:$interface)AND collectd_type:if_octets AND host 


© Average rx * Options 
这 里 使 用 了 ES 的 Derivative 


聚合 函数 求 斜 率 ， 为 保证 
聚合 结果 正确 ， 下 面 需要 
填 入 正确 的 单位 ， 和 后 面 
的 Legend 配 置 保持 一 致 


Unit Second 


Date Histogram @timestamp * Interval: 1m 


Interval 1m 





现在 这 个 图 形 就 会 跟着 上 面 网 卡 名 的 改变 而 改变 了 。 如 果 布 望 选 择 AL1 的 时 候 ， 
能 同时 展示 多 块 网 卡 ， 需 要 把 这 一 个 panel 进 行 重复 就 可 以 了 ， 在 General 选项 卡 
启用 repeat 


Network Traffic on eth0 


2016-11-28 01:05:00 
一 接受 速率 : 137.4 kBps e 
= ==: 222.6 kBps avg curren 
Bps 143.5 kBps 


04:00 05:00 06:00 07:00 08:00 09:00 10:00 


223.0 kBps 160.2 kBps 


General Metrics Axes Legend Display Time range 


Network Traffic on Sinter Span 4 vv Height Transparent 


Repeat Panel interface v Min span 1 M 


Drilldown / detail link @ 


+ Add link 





当 网 卡 名 选择 All 的 时 候 ， 就 会 将 所 有 的 网 卡 流量 曲线 图 repeat 成 一 行 (row): 


Network Traffic on eth0 Network Traffic on eth1 Network Traffic on tun0 
300 kBps 30 kBps 1.0 Bps 
250 kBps 25 kBps 0.5 Bps 
200 kBps 20 kBps 
0 Bps 
150 kBps 15 kBps 
100 kBps 10 kBps -0.5 Bps 


50 kBps 5 kBps -1.0 Bps 


F 
00:00 04:00 08:00 12:00 00:00 4:00 08:00 12:00 00:00 08:00 12:00 


avg current avg current avg current 
一 接受 速率 180.5 kBps 80.7 kBps 一 接受 速率 25.57 kBps 15.12 kBps 


一 发 送 速率 222.8kBps 129.3 kBps 一 发 送 速率 14.00 kBps 9.69 kBps 





同 理 ， 如 果 Templating 那里 将 Multi-value 勾 选 上 ， 那 么 网 卡 名 这 里 就 可 以 勾 
选 上 你 希望 展示 的 网 卡 名 ， 并 不 限于 单 选 。 


现在 再 回 到 一 开始 遗留 的 问题 ，host 匹 配 的 问题 ， 利 用 模板 的 特性 就 可 以 非常 优雅 
的 搞定 这 个 问题 。 


创建 一 个 host 的 模板 : 


Templating Variables 


Variable 


Name 


Label 


Query Options 


Data source » Refresh On Dashboard Load 
Query {"find": "terms", "field": "host") 


Regex 


Selection Options 


Multi-value 


Include All option 


Value groups/tags (Experimental feature) 


Enable 





这 样 前 面 所 有 的 查询 Query 再 追加 一 个 条 件 AND host:$host ， 就 可 以 对 每 个 主 
机 生成 一 个 单独 的 dashboard 界 面 了 : 


$8 Detail-Server - c © Today so far 


间隔 : auto» ”主机 名 :| 网 卡 名 : Al 挂 载 点 : All > 器 New dashboard $$ Nginx dashboard ”器 Postgesql-Dashbord — 88 Servers-Overview — 88 


Load Average 


current current 
im — 144 idle 996 
5m 187 z interrupt 0% 
EI MET nai — nice 1% 
E 
steal 
system 
user 


wait 


Swap Usage 
current 19 current 

buttered 30.12 MiB cher 46 MiB. 

cached GiB re MiB 

free 208.73 MiB 

slab_recl 83.89 MiB 


EN 3158 MiB 
" 954 MiB 
used 6.08 GiB 


10:00 12 


Network Traffic on etho Network Traffic on eth1 Network Traffic on tuno 


04:00 0 00 12:0 0:0 0 0 8:00 0:0 12:00 6 00 0 12:00 


current a current avg current 


ZoomOut > @Last5 minutes 


Row settings 


Row details Templating options 


Tite EX [LED] Height 200px ¥ Show Title Repeat Row host 


s: Servers-Overview ~ [ € zoomou > © Last5 minutes 


间隔 : auto» ”服务 器 器 Detail-Server 器 New dashboard ”器 Nginx dashboard ”器 Postgesql-Dashbord 88 


主机 名 : 


System Uptime CPU of user Disk on mnt Used Memory Load on 1m 


free 


主机 名 


System Uptime CPU of user Disk on mnt Used Memory Load on 1m 


used: 672 GiB (68.2596) 


主机 名 : 


System Uptime CPU of user Disk on mnt Used Memory Load on 1m 


每 行 一 个 服务 器 的 概览 图 ，repeat 之 后 就 可 以 将 多 个 服务 器 的 主要 指标 放 在 一 个 
dashborad 中 了 。 


grafana 的 玩法 还 有 曼 慢 发 握 ， 更 多 详情 可 以 参考 官方 文档 。 





grafana 提 供 了 一 些 在 线 资源 ， 可 以 帮助 使 用 者 更 方便 的 使 用 grafana > Hote 4€ 7X, 
dashboard( https://grafana.net/dashboards ) 可 以 帮助 快速 生成 一 个 美观 的 
dashboard， 不 用 自己 花心 思 去 布局 了 ， 再 比如 在 线 的 插件 仓库 ( 
https://grafana.net/plugins ) 可 以 帮助 连接 其 他 数据 源 ， 如 zabbix，Open-Falcon 
等 ， 或 添加 其 他 展示 图 表 ， 如 人 饼 图 (Pie chat) ° 


合理 利用 这 些 在 线 资源 可 以 让 grafana 更 加 完善 易 用 。 


e grafana'E 7 3: 43: http://docs.grafana.org/ 
e elasticsearch E 7 3 4: 
https://www.elastic.co/guide/en/elasticsearch/reference/2.4/index.html 


juttle 介绍 


juttle 是 一 个 nodejs 项 目 ， 专 注 于 数据 处 理 和 可 视 化 。 它 自 定 义 了 一 套 自己 的 
DSL ， 提供 交互 式 命令 行 、 程 序 运 行 、 界 面 访问 三 种 运行 方式 。 


在 juttle 的 DSL 中， 可 以 用 | 管道 符 串 联 下 列 指令 实现 数据 处 理 : 


e 通过 read 指令 读 取 来 自 http、file、elasticsearch、graphite、influxdb、 
opentsdb ` mysql 等 数据 源 ， 

过 filter 指令 及 自 定义 的 JavaScript 函数 做 数据 过 滤 ， 

过 reduce 指令 做 数据 有 聚合， 

join 指令 做 数据 关联 ， 

e write 指令 做 数据 转 储 ， 

e 通过 view 指令 做 数据 可 视 化 。 


通 
通 
更 关键 的 ， 可 以 用 () 并 联 同一 层级 的 多 条 指令 进行 处 理 。 


看 起 来 非常 有 意思 的 项 目 ， 赶 紧 试 试 吧 。 


ede x 
RBA 
既然 说 了 这 是 一 个 nodejs 项 目 ， 自 然 是 通过 npm 安装 了 : 


sudo npm install -g juttle 
sudo npm install -g juttle-engine 


注意 ， 如 果 是 在 MacBook 上 安装 的 话 ， 一 定 要 先 通过 AppStore 安装 好 Xcode 并 
确认 完 license ° nom 安装 依赖 的 sqlite3 的 时 候 没 有 xcode 会 僵 死 在 那 。 


juttle 包 提供 了 命令 行 交互 ，juttle-engine 包 提 供 了 网 页 访问 的 服务 器 。 


juttle 的 配置 文件 默认 读 取 位 置 是 $HOME/.juttle/config.json 。 比 如 读 取 本 机 
elasticsearch 的 数据 ， 那 么 定义 如 下 : 


juttle 


{ 
"adapters": { 
elastic: 1 
"address": "localhost", 
"port": 9200 
j 
} 
} 


甚至 可 以 读 取 多 个 不 同 来 源 的 elasticsearch， 这 样 : 


{ 
"adapters": 1 
"elastic": [{ 
"qd s WONEN, 
"address": "localhost", 
"port": 9200 
} i 
a ENOG 
"address": "localhost", 
“port: 9201 
3l; 
Uu Dux s =f 
"url": "http://examples influxdb 1:8086", 
“Ser 2 "Fool; 
"password": "root" 
} 
} 
} 


命令 行 运 行 示例 


配置 完成 ， 就 可 以 交互 式 命令 行 运行 了 。 终 端 输入 juttle 回 车 进入 交互 


我 们 输入 下 面 一 段 查询 : 


6] 


id o 


juttle> read elastic -id one -index 'logstash-*' -from :1 year 
ago: -to :now: 'MacBook-Pro' | reduce -every :1h: c = count() by 
path | filter c » 1000 | put line - 10000 | view table -columnO 
rder 'time', 'c', 'line', 'path' 


输出 如 下 : 


| time | c | line | pat 
h | 
-上 一 一 一 
大 
| 2016-03-02T10:00:00.000Z | 4392 | 10000 | /va 


r/log/system.log | 


— | 


| 2016-03-02T11:00:00. 000Z | 4818 | 10000 | /va 
r/log/system. log | 


下 一 
一 


| 2016-03-02T12:00:00.000Z | 2038 | 10000 | /va 
r/log/system.log | 


— | 


| 2016-03-02T13:00:00.000Z | 1826 | 10000 | /va 
r/log/system. log | 


一 一 一 一 一 一 一 一 一 一 一 一 一 


| 2016-03-02T15:00:00.000Z | 10267 | 10000 | /va 
r/log/system.log | 


一 


| 2016-03-02T16:00:00.000Z | 10999 | 16000 | /va 
r/log/system.log | 


一 


| 2016-03-02T17:00:00.000Z | 3528 | 10000 | /va 
r/log/system.log | 


六 
A 


Ab 


一 
一 


| 2016-03-03T00:00:00.000Z | 2498 | 10000 | /va 
r/log/system. log | 


-一 
一 


| 2016-03-03T03:00:00.000Z | 4600 | 10000 | /va 
r/log/system.log | 


一 
一 


| 2016-03-03T04:00:00.000Z | 7751 | 10000 | /va 
r/log/system.log | 


_-— ~ y y 
一 一 一 一 一 一 一 一 一 一 一 一 一 


| 2016-03-03T05:00:00.000Z | 3249 | 10000 | /va 
r/log/system.log | 


下 一 
一 


| 2016-03-03T06:00:00.000Z | 5715 | 10000 | /va 
r/log/system. log | 
-一 一 
2 


| 2016-03-03TO7:00:00.000Z | 4374 | 10000 | /va 
r/log/system. log | 


下 一 
一 


| 2016-03-03T08:00:00.000Z | 2600 | 10000 | /va 
r/log/system. log | 


互 ， 所 以 除了 个 别 已 经 提前 实现 好 了 的 reduce 方法 可 以 转换 成 aggregation 以 


外 ， 其 他 的 juttle 指令 ， 都 是 通过 query 把 数据 拿 回 来 以 后 ， 由 juttle 本 身 做 的 运 


理 。juttle-adapter-elastic #24249 DEFAULT_FETCH_SIZE 设置 是 10000 条 。 


需要 注意 的 是 ，juttle 和 es-hadoop 一 样 ， 也 是 通过 RESTful API 和 elasticsearch 


JE 


Ar 


而 比 es-hadoop 24% = * AA juttle 是 单机 程序 ， 它 还 没有 像 es-hadoop 那样 并 
发 partition 直 连 每 个 elasticsearch 的 shard 做 并 发 请 求 。 


juttle-viz J 31167 d 


上 一 小 节 介 绍 了 一 下 怎么 用 jutte 交互 式 命令 行 查看 表格 式 输出 。juttle 事实 上 还 提 
供 了 一 个 web 服务 器 ， 做 数据 可 视 化 效果 ， 这 个 同样 是 用 juttle 语言 描述 配置 。 


我 们 已 经 安装 好 了 juttle-engine 模块 ， 那么 直接 启动 服务 器 即 可 : 
~$ juttle-engine -d 


然后 浏览 器 打开 http://localhost:8080 就 能 看 到 页 面 了 。 注 意 ， 请 使 用 
Chrome v45 以 上 版 本 或 者 Safari 等 其 他 浏览 器 ， 否 则 有 个 Array 上 的 bug ^ 

但 是 目前 这 个 页 面 上 本 身 不 提供 输入 框 直接 写 juttle 语言 。 所 以 需要 我 们 把 juttle 语 
言 写成 脚本 文件 ， 再 来 通过 页 面 加 载 。 


-$ cat > ~/test.juttle ««EOF 
read elastic -index 'logstash-*' -from :-2d: -to :now: 'MacBook 
-Pro' 
| reduce -every :1h: count() by 'path.raw' 
| 人 
view timechart -row 0 -col 0;; 
view table -height 200 -row 1 -col 0; 
view piechart -row 1 -col 0; 


); 


read elastic -index 'logstash-*' -from :-2d: -to :-1d: 'MacBo 
ok-Pro' AND '/var/1log/system.log' 
| reduce -every :1h: count(); 

read elastic -index 'logstash-*' -from :-1d: -to :now: 'MacBo 
ok-Pro' AND '/var/1log/system.log' 
| reduce -every :1h: count(); 


view timechart -duration :1 day: -overlayTime true -height 
400 -row O -col 1 -title 'syslog hour-on-hour'; 
view table -height 200 -row 1 -col 1; 
); 
EOF 


然后 访问 http://localhost:8080?path-/test.juttle ， 注 意 这 里 的 path 参 数 
的 写法 ， 这 个 /其 实 指 的 是 你 运行 juttle-engine 命令 的 时 候 的 路 径 ， 而 不 是 站 
的 设备 根 目 录 。 


就 可 以 在 浏览 器 上 看 到 如 下 效果 : 


path.raw: /var/log/authd.log path.raw: /var/log/commerce.log 
W path.raw: /var/log/corecaptured.log W path.raw: /var/log/fsck_hfs.log syslog hour-on-hour 
WB path.raw: /var/log/install.log E path.raw: /var/log/system.log BB count count (1 day ago) 
path.raw: /var/log/wifi.log 
18k 
18k 
16k 
rm 14k 
Thu Mar 17 07:58:17 2016 UTC 42k 


10k 


path.raw: /var...log/fsck_hfs. ins 


path.raw: /var/log/system.log: 4,898 


Ne 
12:00 Thu 17 12:00 Fri 18 


12:00 Thu 17 12:00 Fri 18 


00:08:51 on Wed Mar 16 2016 to 00:08:51 on Fri Mar 18 2016 (UTC) 
2 days 00:08:51 on Wed Mar 16 2016 to 01:00:00 on Fri Mar 18 2016 (UTC) 


12:00 


time nt path.raw uM og: 780 time 
Wed Mar /var/log/system.log Wed Mar 16 14:00:00 2016 UTC 
16 /wifi.log: 21.0 — . 

: : istall.lo. 17,0 ~ e: Wed Mar 16 15:00:00 2016 UTC 
BESO erce. “log: 3.00 — 4 SN 
2016 UTC = Wed Mar 16 16:00:00 2016 UTC 


Wed Mar 2 /var/log/system.log Wed Mar 16 17:00:00 2016 UTC 
16 

15:00:00 Wed Mar 16 18:00:00 2016 UTC 
2016 UTC Wed Mar 16 19:00:00 2016 UTC 


Wed Mar 2131  /var/log/system.log \ /var/log/syste Wed Mar 16 20:00:00 2016 UTC 





01:00:00 on Fri Mar 18 2016 (UTC) 


页 面 上 还 有 一 行 有 关 path.raw 的 WARNING 提示 ， 那 是 因为 juttle E ay xt 
elasticsearch 的 mapping 解析 支持 的 不 是 很 好 ， 但 是 不 影响 使 用 ， 可 以 不 用 管 


可 视 化 相关 指令 介绍 
我 们 可 以 看 到 这 次 的 juttle 脚本 ， 跟 昨天 在 命令 行 下 运行 的 几 个 区 别 : 


1. 我 们 用 上 了 O ， 这 是 juttle 的 一 大 特技 ， 对 同一 结果 并 联 多 个 view > RH 
并 联 多 个 输入 结果 做 相同 的 后 续 处 理 等 等 。 
2. 我 们 对 view 用 上 了 row 和 col 参数 ， 用 来 指定 他 们 在 页 面 上 的 布局 。 
3. 有 一 个 timechart 我 们 用 了 -durat :1d: -overlayTime true 参数 。 
这 是 timechart 独 有 的 参数 ， 专 门 用 来 实现 同比 环比 的 。 在 图 上 的 效果 大 
is 了 。 不 过 目前 也 有 人 小 问题 ， 就 是 鼠标 放 到 图 上 的 时 候 ， 只 能 看 到 
二 个 结果 的 指标 说 明 ， 看 不 到 第 一 个 的 。 


Kale 系统 


Kale 系统 是 Etsy 公司 开源 的 一 个 监控 分 析 系 统 。Kale 分 为 两 个 部 分 : skyline 和 
oculus » skyline 负责 对 时 序数 据 进行 概率 分 布 校 验 ， 对 校 验 失败 率 超 过 阅 值 的 时 序 
数据 发 报警 ; oculus 负责 给 被 报警 的 时 序 ， 找 出 趋势 相似 的 其 他 时 序 作 为 关联 性 参 
A e 

看 到 “相似 ”两 个 字 ， 你 一 定 想到 了 。 没 错 ，oculus 组 件 ， 就 是 利用 了 Elasticsearch 
的 相似 度 打分 。 


oculus 中 ， 为 Elasticsearch 的 
org.elasticsearch.script.ExecutableScript 扩展 了 DTW 和 

Euclidian 两 种 NativeScript。 可 以 在 界面 上 选择 用 其 中 茶 一 种 算法 来 做 相似 度 
打分 : 


ganglia.webs. ——— ml =: ses.apache_requests_per_second.sum 
score: 0.0 | Add Exclusion Filter | Add To Collection 


2013/06/11 08:45:15: Value:20.68 


22 
21 


20 








08:45 08:50 08:55 09:00 09:05 09:10 09:15 09:20 09:25 09:30 09:35 09:40 09:45 09:50 
1 Hour 


ganglia.webs. mm  m-— s— apache requests per second.sum 
score: 465.40076 | Add Exclusion Filter | Add To Collection 


^ 


21 


20 








08:45 08:50 08:55 09:00 09:05 09:10 09:15 09:20 09:25 09:30 09:35 09:40 09:45 09:50 
1 Hour 


ganglia.webs. we se meg gee-pkts_out.sum 
score: 502.51923 | Add Exclusion Filter | Add To Collection 


6500 
6000 


5500 | 


08:45 08:50 08:55 09:00 09:05 09:10 09:15 09:20 09:25 09:30 09:35 09:40 09:45 09:50 
1 Hour 








后 相似 度 最 高 的 几 个 时 序 图 就 依次 排列 出 来 了 。 
Euclidian 即 欧 几 里 得 距离 ， 是 时 序 相 似 度 计 算 里 最 基础 的 方式 。 


DWT 即 动态 时 间 规整 (Dynamic Time Warping)， 也 是 时 序 相似 度 计算 的 常 

式 ， 它 和 欧 几 里 得 距离 的 差别 在 于 ， 欧 几 里 4 人 
的 ， 而 动态 时 间 规 整 计算 的 时 序数 据 并 不 要 求 长 度 相等 。 在 运 维 监控 来 说 ， 也 就 是 
延 后 一 定时 间 发 生 的 相近 a e e 


Ait * oculus 插件 仅 更 新 到 支持 Elasticsearch-0.90.3 "KAA 3E. » Etsy 性 能 优化 团 
KÆ Oreilly 2015 大 会 上 透露 ， 他 们 内 部 已 经 根据 Kale 的 经 验 教训 ， 重 新 开发 了 
Kale 2.0 版 。 会 在 年 内 开源 放出 来 。 大 家 一 起 期 待 吧 ! 


参考 阅读 


Etsy Kale + 3i #22 


http://codeascraft.com/2013/06/11/introducing-kale/ 
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Logstash 早期 曾经 自 带 了 一 个 特别 简单 的 logstash-web 用 来 查看 ES 中 的 数据 。 
其 功能 太 过 简单 ， 于 是 Rashid Khan 用 PHP 写 了 一 个 更 好 用 的 web， 取 名 叫 
Kibana ° 3& 4- PHP 版 本 的 Kibana 发 布 时 间 是 2011 年 12 月 11 日 。 


Kibana 迅速 流行 起 来 ， 不 久 的 2012 年 8 月 19 A > Rashid Khan 用 Ruby € S f 
Kibana， 也 被 叫做 Kibana2。 因 为 Logstash 也 是 用 Ruby 写 的 ， 这 样 Kibana 就 可 
以 替代 原先 那个 简陋 的 logstash-web 页 面 了 。 


目前 我 们 看 到 的 angularjs 版 本 kibana 其 实 原 名 叫 elasticsearch-dashboard， 但 跟 
Kibana2 作者 是 同一 个 人 ， 换 和 句 话说 ，kibana +t logstash 还 早 就 进 了 
elasticsearch 名 下 。 这 个 项 目 改 名 Kibana 是 在 2014 年 2 月， 也 被 叫做 
Kibana3。 全 新 的 设计 一 下 子 风 靡 DevOps 界 。 随 后 其 他 社区 纷纷 借鉴 ，Graphite 
目前 最 流行 的 Grafana 界面 就 是 由 此 而 来 ， 至 今 代 码 中 还 留存 有 十 余 处 kbn 字样 。 


2014 年 4 A > Kibana3 停止 开发 ，ES 公司 集中 人 力 开 始 Kibana4 的 重 构 ， 在 
2015 年 初 发 布 了 使 用 JRuby 做 后 端的 beta MÆ > T 3 月 正式 推出 使 用 node.js 做 
后 端的 正式 版 。 由 于 设计 思路 上 的 差别 ， 一 些 K3 适宜 的 场景 并 不 在 KA 考虑 范围 
内 ， 所 以 ， 至 今 K3 和 K4 并 存 使 用 。 本 书 也 会 分 别 讲解 两 者 。 


注释 


配置 参数 内 容 部 分 译 自 Elasticsearch 官方 指南 Kibana 部 分 ， 其 中 v3 的 panel 
分 额外 添加 了 截图 注释 。 然 后 在 使 用 的 基础 上 ， 添 加 了 原创 的 源码 解析 ， 场 景 示 
例 ， 二 次 开发 入 门 等 内 容 。 


安排 、 配 置 和 运行 


Kibana4 安装 方式 依然 简单 ， 你 可 以 在 几 分钟 内 安装 好 Kibana 然后 开始 探索 你 的 
Elasticsearch 索引 。 只 需要 预备 : 


e Elasticsearch 1.4.4 或 者 更 新 的 版 本 

e 一 个 现代 浏览 器 - 支持 的 浏览 器 列表 . 

e 有 关 你 的 Elasticsearch 集群 的 信息 息 : 
o 你 想 要 连接 Elasticsearch 实例 的 URL 
o 你 想 搜索 哪些 Elasticsearch 索引 


如 果 你 的 Elasticsearch 是 被 Shield 保护 着 的 ， 阅 读 生产 环境 部 署 章节 相关 内 
容 学 习 额 外 的 安装 说 明 e 


安装 并 启动 kibana 
要 安装 户 动 Kibana: 


1. 下 载 对 应 平台 的 Kibana 4 二 进 制 包 

2. 解压 ,zip 或 tar.gz 压缩 文件 

3. 在 安装 目录 里 运行 : bin/kibana (Linux/MacOSX) 或 bin\kibana.bat 
(Windows) 


完毕 | Kibana 现在 运行 在 5601 端口 了 。 


让 kibana 连接 到 elasticsearch 


在 开始 用 Kibana 之 前 ， 你 需要 告诉 它 你 打算 探索 哪个 Elasticsearch 索引 。 第 一 次 
访问 Kibana 的 时 候 ， 你 会 被 要 求 定义 一 个 index pattern 用 来 匹配 一 个 或 者 多 个 索 
引 名 。 好 了 。 这 就 是 你 需要 做 的 全 部 工作 。 以 后 你 还 可 以 随时 从 Settings 标签 页 添 
加 更 多 的 index pattern ° 


默认 情况 下 ，Kibana 会 连接 运行 在 localhost 的 Elasticsearch。 要 连接 其 
他 Elasticsearch 实例 ， 修 改 kibana.yml 里 的 Elasticsearch URL， 然 后 重 
È Kibana。 如 何在 生产 环境 下 使 用 Kibana， 阅 读 生产 环境 部 署 章节 。 


要 从 Kibana 访问 的 Elasticsearch 索引 的 配置 方法 : 


1. 从 浏览 器 访问 Kibana 界面 。 也 就 是 说 访问 比如 localhost:5601 或 者 
http://YOURDOMAIN.com:5601 ° 
Configure an index pattern 


In order to use Kibana you must configure at least one index pattern. Index patterns are used to identify the Elasticsearch index to run search and analytics against. They 
are also used to configure fields. 


Index contains time-based events 
Use event times to create index names [DEPRECATED] 


Index name or pattern 


Patterns allow you to define dynamic index names using * as a wildcard. Example: logstash-* 
logstash-* 


Do not expand index pattern when searching (Not recommended) 


By default, searches against any time-based index pattern that contains a wildcard will automatically be expanded to query only the indices that contain data within 
the currently selected time range. 


Searching against the index pattern /ogstash-* will actually query elasticsearch for the specific matching indices (e.g. logstash-2015.12.21) that fall within the current 
time range. 


Time-field name @ refresh fields 


2. 指定 一 个 可 以 匹配 一 个 或 者 多 个 Elasticsearch 索引 的 index pattern 。 默 认 情 
况 下 ，Kibana 认为 你 要 访问 的 是 通过 Logstash 导入 Elasticsearch 的 数据 。 
这 时 候 你 可 以 用 默认 的 logstash-* 作为 你 的 index pattern。 通 配 符 (*) 匹配 
索引 名 中 零 到 多 个 字符 。 如 果 你 的 Elasticsearch 索引 有 其 他 命名 约定 ， 输 入 
合适 的 pattern » pattern 也 开始 是 最 简单 的 单个 索引 的 名 字 。 

3. 选择 一 个 包含 了 时 间 惟 的 索引 字段 ， 可 以 用 来 做 基于 时 间 的 处 理 。Kibana 会 读 
取 索 引 的 映射 ， 然 后 列 出 所 有 包含 了 时 间 改 的 字段 ( 译 者 注 : 实际 是 字段 类 型 为 
date 的 字段 ， 而 不 是 “看 起 来 像 时 间 惟 "的 字段 )。 如 果 你 的 索引 没有 基于 时 间 的 
数据 ， 关 闭 Index contains time-based events 参数 。 

4. 如 果 一 个 新 索引 是 定期 生成 ， 而 且 索 引 名 中 带 有 时 间 惟 ， 选 择 Use event 
times to create index names 选项 ， 然 后 再 选择 Index pattern 
interval 。 这 可 以 提高 搜索 性 能 ，Kibana 会 至 搜索 你 指定 的 时 间 范 围 内 的 索 
引 。 在 你 用 Logstash 输出 数据 给 Elasticsearch 的 情况 下 尤其 有 效 。 

5. 点 击 Create 添加 index pattern。 第 一 个 被 添加 的 pattern 会 自动 被 设置 为 
默认 值 。 如 果 你 有 多 个 index pattern 的 时 候 ， 你 可 以 在 Settings > 
Indices 里 设置 具体 哪个 是 默认 值 。 


好 了 。Kibana 现在 连接 上 你 的 Elasticsearch 数据 了 。Kibana 会 显示 匹配 上 的 索引 
里 的 字段 名 的 只 读 列表 。 


开始 探索 你 的 数据 ! 


你 可 以 开始 下 钻 你 的 数据 了 : 


e # Discover 页 搜索 和 浏览 你 的 数据 。 
e 在 Visualize 页 转换 数据 成 图 表 。 
e 在 Dashboard 页 创建 定制 自己 的 仪表 板 。 


生产 环境 部 轩 


Kibana5 是 是 一 个 完整 的 web 应 用 。 使 用 时 ， 你 需要 做 的 只 是 打开 浏览 器 ， 然 后 输 
入 你 运行 Kibana 的 机 器 地 址 然后 加 上 端口 号 。 比 如 说 : localhost:5601 或 者 
http://YOURDOMAIN.com:5601 ° 


但 是 当 你 准备 在 生产 环境 使 用 Kibanad 的 时 候 ， 比 起 在 本 机 运行 ， 就 需要 多 考虑 一 
些 问 题 : 


e 在 哪 运 行 kibana 
e 是 否 需 要 加 密 Kibana 出 入 的 流量 
e 是 否 需 要 控制 访问 数据 的 权限 


Nginx 代理 配置 


因为 Kibana5 不 再 是 Kibana3 那 种 纯 静 态 文件 的 单 页 应 用 ， 所 以 其 服务 器 端 是 需 
要 消耗 计算 资源 的 。 因此 ， ， 如 果 用 户 较 多 , Kibana5 ASA 能 需 进行 多 多 点 部 
署 ， 这 时 候 ， 就 需要 用 Nginx 做 一 层 代 理 了 。 


和 Kibana3 相 比 ，Kibana5 的 Nginx 代理 配置 倒是 简单 许多 > dee 统 
一 配置 的 。 下 面 是 一 段 包含 入 口 流 量 加 密 、 简 单 权限 控制 的 Kibana5 代理 配置 


upstream kibanab5 { 
server 127.0.0.1:5601 fail_timeout=0; 


} 
server { 
listen PB 
server name kibana server; 
access log /var/log/nginx/kibana.srv-log-dev.1log; 
error_log /var/log/nginx/kibana.srv-log-dev.error 
. log; 
ssl on; 
ssl certificate /etc/nginx/ssl/all.crt; 
ssl certificate key /etc/nginx/ssl/server.key; 
location / { 
root /var/www/kibana; 
index index.html index.htm; 
} 
location ~ ^/kibana5/.* { 
proxy_pass http://kibana5; 
rewrite ^/kibana5/(.*) /$1 break; 
proxy_set_header X-Forwarded-For $proxy_add_x_forwar 
ded_for; 
proxy_set_header Host $host; 
auth_basic "Restricted"; 
auth_basic_user_file /etc/nginx/conf.d/kibana.myhost.org 
. htpasswd; 
} 
} 


如 果 用 户 够 多 ， 当 然 你 可 以 单独 跑 一 个 kibana5 集群 ， 然 后 在 upstream 配置 段 
中 添加 多 个 代理 地 址 做 负载 均衡 。 


配置 Kibana 和 shield 一 起 工作 


Nginx 只 能 加 密 和 管理 浏览 器 到 服务 器 端的 请 求 ， 而 Kibanad 到 ELasticsearch 集 

群 的 请 求 ， 就 需要 由 Elasticsearch 方面 来 完成 了 。 如 果 你 在 用 Shield 做 

Elasticsearch 用 户 认 证 ， 你 需要 给 Kibana 提供 用 户 赁 证 ， 这 样 它 才能 访问 
.kibana 索引 。Kibana 用 户 需要 由 权限 访问 .kibana 索引 里 以 下 操作 : 


' .kibana': 
- indices:admin/create 
- indices:admin/exists 
- indices:admin/mapping/put 
- indices:admin/mappings/fields/get 
- indices:admin/refresh 
- indices:admin/validate/query 
- indices:data/read/get 
- indices:data/read/mget 
- indices:data/read/search 
- indices:data/write/delete 
- indices:data/write/index 
- indices:data/write/update 
- indices:admin/create 


更 多 配置 Shield 的 内 容 ， 请 阅读 官网 的 Shield with Kibana 4。 


要 配置 Kibana 的 赁 证， 设置 kibana.yml 里 的 
kibana_elasticsearch_username 和 kibana_elasticsearch_password i 
项 即 可 : 


# If your Elasticsearch is protected with basic auth: 
kibana elasticsearch username: kibana5 
kibana elasticsearch password: kibana5 


# ssl 
Kibana 同时 支持 对 客户 端 请 求 以 及 Kibana 服务 器 发 往 Elasticsearch 的 请 求 做 
SSL aa € © 


要 加 密 浏览 器 (或 者 在 Nginx 代理 情况 下 ，Nginx 服务 器 ) 到 Kibana 服务 器 之 间 的 通 
言 ， 配 置 kibana.yml 里 的 ssl key file 和 ssl cert file 参数 : 


# SSL for outgoing requests from the Kibana Server (PEM formatte 
d) 

ssl key file: /path/to/your/server.key 

ssl cert file: /path/to/your/server.crt 


如 果 你 在 用 Shield 或 者 其 他 提供 HTTPS 的 代理 服务 器 保护 Elasticsearch， 你 可 以 
配置 Kibana 通过 HTTPS 方式 访问 Elasticsearch， 这 样 Kibana 服务 器 和 
Elasticsearch 之 间 的 通信 也 是 加 密 的 。 


要 做 到 这 点 ， 你 需要 在 kibana.yml 里 配置 Elasticsearch 的 URL 时 指明 是 
HTTPS 协议 : 


elasticsearch: "https://<your_elasticsearch_host>.com:9200" 


如 果 你 给 Elasticsearch 用 的 是 自己 签名 的 证 书 ， 请 在 kibana.yml 里 设 定 ca 
参数 指明 PEM 文件 位 置 ， 这 也 意味 着 开启 了 verify ssl X: 


# If you need to provide a CA certificate for your Elasticsarech 
instance, put 

# the path of the pem file here. 

ca: /path/to/your/ca/cacert.pem 


控制 访问 权限 


你 可 以 用 Elasticsearch Shield 来 控制 用 户 通 过 Kibana 可 以 访问 到 的 
Elasticsearch 数据 。Shield 提供 了 索引 级 别 的 访问 控制 。 如 果 一 个 用 户 没 被 许可 运 
行 这 个 请 求 ， 那 么 它 在 Kibana 可 视 化 界面 上 只 能 看 到 一 个 空白 。 


要 配置 Kibana 使 用 Shield， 你 要 为 Kibana 创建 一 个 或 者 多 个 Shield 角色 (role)， 
以 kibana5 作为 开头 的 默认 角色 。 更 详细 的 做 法 ， 请 阅读 Using Shield with 
Kibana 4 ° 


discover 功能 


Discover cd uq cum M USE m usui EE 你 选择 的 索引 模 
式 的 每 个 索引 的 每 条 记录 。 你 可 以 提交 搜索 请 求 ， 过 滤 搜 索 结 果 ， 然 后 查看 文档 数 
据 。 你 还 可 以 看 到 匹配 搜索 请 求 的 文档 总 数 ， 获 取 字 段 值 的 统计 情况 。 如 果 索 引 模 
式 配 置 了 时 间 字 段 ， 文 档 的 时 序 分 布 情况 会 在 页 面 顶部 以 柱状 图 的 形式 展示 出 来 。 


pt at AY Ya) 33 28 5 


时 间 过 滤器 (Time Filter) 限 制 搜索 结果 在 一 个 特定 的 时 间 周 期 内 。 如 果 你 的 索引 包含 
的 是 时 序 诗句 ， 而 且 你 为 所 选 的 索引 模式 配置 了 时 间 字 段 ， 那 么 就 就 可 以 设置 时 间 
过 滤器 。 


默认 的 时 间 过 滤器 设置 为 最 近 15 分 钟 。 你 可 以 用 页 面 顶 部 的 时 间 选 择 器 (Time 
Picker) 来 修改 时 间 过 滤器 ， 或 者 选择 一 个 特定 的 时 间 间 隔 ， 或 者 直方 图 的 时 间 范 
o 


要 用 时 间 选 择 器 来 修改 时 间 过 滤器 : 


1. 点 击 菜 单 栏 右上 角 显 示 的 Time Filter 打开 时 间 选 择 器 。 

2. 快速 过 滤 ， 直 接 选 择 一 个 短 链 接 即 可 。 

3. 要 指定 相对 时 间 过 滤 ， 点 击 Relative 然后 输入 一 个 相对 的 开始 时 间 。 可 以 是 任 
意 数 字 的 秒 、 分 、 小 时 、 天 、 月 其 至 年 之 前 。 

4. 要 指定 绝对 时 间 过 滤 ， 点 击 Absolute 然后 在 From 框 内 输入 开始 日 期 ，To 4 
内 输入 结束 日 期 。 

5. 点 击 时 间 选 择 器 底部 的 箭头 隐藏 选择 器 。 


要 从 柱状 图 上 设置 时 间 过 滤器 ， 有 以 下 几 种 方式 : 


。 想 要 放大 那个 时 间 间 隔 ， 点 击 对 应 的 柱 体 。 
。 单 击 并 拖 搜 一 个 时 间 区 域 。 注 意 需要 等 到 光标 变 成 加 号 ， 才 意味 着 这 是 一 个 有 
效 的 起 始点 。 


你 可 以 用 浏览 器 的 后 退 键 来 回 退 你 的 操作 。 


搜索 数据 


在 Discover 页 提交 一 个 搜索 ， 你 就 可 以 搜索 匹配 当前 索引 模式 的 索引 数据 了 。 你 
可 以 直接 输入 简单 的 请 求 字 符 串 ， 也 就 是 用 Lucene query syntax， 也 可 以 用 完整 
的 基于 JSON 的 Elasticsearch Query DSL ° 


当 你 提交 搜索 的 时 候 ， 直 方 图 ， 文 档 表 格 ， 字 段 列表 ， 都 会 自动 反映 成 搜索 的 结 
果 。hits( 匹 配 的 文档 ) 总 数 会 在 直方 图 的 右上 角 显 示 。 文 档 表格 显 示 前 500 个 匹配 
文档 。 默 认 的 ， 文 档 倒 序 排列 ， 最 新 的 文档 最 先 显示 。 你 可 以 通过 点 击 时 间 列 的 头 
部 来 反 转 排序 。 事 实 上 ， 所 有 建 了 索引 的 字段 ， 都 可 以 用 来 排序 ， 稍 后 会 详细 说 
AF o 


要 搜索 你 的 数据 : 


1. 在 搜索 框 内 输入 请 求 字 符 串 : 

o 简单 的 文本 搜索 ， 直 接 输 入 文本 字符 串 。 比 如 ， 如 果 你 在 搜索 网 站 服务 器 
日 志 ， 你 可 以 输入 safari 来 搜索 各 字段 中 的 safari 单词 。 

o 要 搜索 特定 字段 中 的 值 ， 则 在 值 前 加 上 字段 名 。 上 比如， 你 可 以 输入 
status:200 来 限制 搜索 结果 都 是 在 status 字段 里 有 200 内 容 。 

o 要 搜索 一 个 值 的 范围 ， 你 可 以 用 范围 查询 语法 ， [START_VALUE TO 
END VALUE] ° Hite > BAAR Axx 的 状态 码 ， 你 可 以 输入 status:[400 
TO 499] 。 

o 要 指定 更 复杂 的 搜索 标准 ， 你 可 以 用 布尔 操作 符 AND, OR ,和 NOT ° 
比如 ， 要 查找 Axx 的 状态 码 ， 还 是 php 或 html 结尾 的 数据 ， 你 可 以 
输入 status:[400 TO 499] AND (extension:php OR 


extension:html) ° 


这 些 例 子 都 用 了 Lucene query syntax。 你 也 可 以 提交 Elasticsearch Query 
DSL 式 的 请 求 。 更 多 示例 ， 参 见 之 前 Elasticsearch 章节 。 


1. 点 击 回 车 键 ， 或 者 点 击 Search 按钮 提交 你 的 搜索 请 求 。 


开始 一 个 新 的 搜索 


要 清除 当前 搜索 或 开始 一 个 新 搜索 ， 点 击 Discover 工具 栏 的 New Search 按钮 。 


保存 搜索 


你 可 以 在 Discover 页 加 载 已 保存 的 搜索 ， 也 可 以 用 作 visualizations 4) Rak » RFE 
一 个 搜索 ， 意 味 着 同时 保存 下 了 搜索 请 求 字 符 串 和 当前 选择 的 索引 模式 。 


要 保存 当前 搜索 : 


1. 点 击 Discover 工具 栏 的 Save Search 按钮 。 
2. 输入 一 个 名 称 ， 点 击 Save » 


加 载 一 个 已 存 搜 索 


要 加 载 一 个 已 保存 的 搜索 : 


1. 点 击 Discover 工具 栏 的 Load Search 按钮 。 
选择 你 要 加 载 的 搜索 。 


如 果 已 保存 的 搜索 关联 到 跟 你 当前 选择 的 索引 模式 不 一 样 的 其 他 索引 上 ， 加 载 这 个 
搜索 也 会 切换 当前 的 已 选 索引 模式 。 


变 你 搜索 的 索引 
当 你 提交 一 个 搜索 请 求 ， 匹 配 当前 的 已 选 索引 模式 的 索引 都 会 被 搜索 。 当 前 模式 楼 
式 会 显示 在 搜索 栏 下 方 。 要 改变 搜索 的 索引 ， 需 要 选择 另外 的 模式 模式 。 
要 选择 另外 的 索引 模式 : 


. 点 击 Discover 工具 栏 的 Settings 按钮 。 
2. 从 索引 模式 列表 中 选取 你 打算 采用 的 模式 。 


关于 索引 模式 的 更 多 细节 ， 请 阅读 稍 后 Setting 功能 小 节 
目 动 刷新 页 面 


亦 可 以 配置 一 个 刷新 间隔 来 自动 刷新 Discover 页 面 的 最 新 索引 数据 。 这 会 定期 重 
新 提交 一 次 搜索 请 求 。 


» 


设置 刷新 闻 隔 后 ， 会 显示 在 菜单 栏 时 间 过 滤器 的 左边 。 
要 设置 刷新 间隔 : 


1. 点 击 菜单 栏 右上 角 的 Time Picker O° 


o 


点 击 Auto refresh 标签 
3. 从 列表 中 选择 一 个 刷新 闻 隔 


o 


0 hits New Save Open Share CAuto-refresh € © Last15 minutes > 


Refresh Interval 


5 seconds 1 minute 1 hour 
10 seconds 5 minutes 2 hour 
30 seconds 15 minutes 12 hour 
45 seconds 30 minutes 1 day 


开启 自动 刷新 后 ，Kibana 的 顶部 栏 会 出 现 一 个 暂停 按钮 和 自动 刷新 的 间隔 ， 点 击 
Pause 按钮 可 以 暂停 自动 刷新 。 


按 字 段 过 滤 


你 可 以 过 滤 搜 索 结果 ， 只 显示 在 茶 字 段 中 包含 了 特定 值 的 文档 。 也 可 以 创建 反 向 过 
滤器 ， 排 除 掉 包含 特定 字段 值 的 文档 。 


你 可 以 从 字段 列表 或 者 文档 表格 里 添加 过 滤器 。 当 你 添加 好 一 个 过 滤器 后 ， 它 会 显 
TA 求 下 方 的 过 滤 栏 里 。 从 过 滤 栏 里 你 可 以 编辑 或 者 关闭 一 个 过 滤器 ， 转 换 
过 滤器 (从 正 向 改 成 反 向 ， 反 之 亦 然 )， 切 换 过 滤器 开关 ， 或 者 完全 移 除 掉 它 。 


要 从 字段 列表 添加 过 滤器 : 


点 击 你 想 要 过 滤 的 字段 名 。 会 显示 这 个 字段 的 前 5 名 数据 。 每 个 数据 的 右 侧 ， 

有 两 个 小 按钮 一 ”一 个 用 来 添加 常规 ( 正 向 ) 过 滤器 ， 一 个 用 来 添加 反 向 过 滤 

2. 要 添加 正 向 过 滤器 ， 点 击 Positive Filter 按钮 Q. 这 个 会 过 滤 掉 在 本 字 
段 不 包含 这 个 数据 的 文档 。 

3. 要 添加 反 向 过 滤器 ， 点 击 Negative Filter #42 Q . 这 个 会 过 滤 掉 在 本 字 
段 包 含 这 个 数据 的 文档 。 


要 从 文档 表格 添加 过 滤器 : 


1. 点 击 表 格 第 一 列 ( 通 常 都 是 时 间 ) 文 档 内 容 左 侧 的 ”Expand #42 ^ 展开 文档 
表格 中 的 文档 。 每 个 字段 名 的 右 侧 ， 有 两 个 小 按钮 一 一 一 个 用 来 添加 常规 ( 正 
向 ) 过 滤器 ， 一 个 用 来 添加 反 向 过 滤器 。 

2， 要 添加 正 向 过 滤器 ， 点 击 Positive Filter 按钮 Q .这 个 会 过 滤 掉 在 本 字 
段 不 包含 这 个 数据 的 文档 。 

3. 要 添加 反 向 过 滤器 ， 点 击 Negative Filter 按钮 Q. 这 个 会 过 滤 掉 在 本 字 


段 包 含 这 个 数据 的 文档 。 
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在 Kibana 的 任意 页 面 创建 过 滤器 后 ， 就 会 在 搜索 输入 框 的 下 方 ， 出 现 椭 圆 形 的 过 
滤 条 件 © 


息 标 移动 到 过 滤 条 件 上 ， 会 显示 下 面 几 个 图 标 : 


58 hits New Save Open Share €  OLasti5minutes > 


Search... 


Ca :We Actions» 


e 过 滤器 开关 点 击 这 个 图 标 ， 可 以 在 不 移 除 过 滤器 的 情况 下 关闭 过 滤 条 件 。 
再 次 点 击 则 重新 打开 。 被 禁用 的 过 滤器 是 条 纹 状 的 灰色 ， 要 求 包含 (相当 于 
Kibana3 里 的 must) 的 过 滤 条 件 显 示 为 绿色 ， 要 求 排除 (相当 于 Kibana3 里 的 
mustNot) 的 过 滤 条 件 显 示 为 红色 。 

e。 过 滤器 图 钉 轿 是 点 击 这 个 图 标 钉 住 过 滤器 。 被 钉 住 的 过 滤器 ， 可 以 横 叶 Kibana 
各 个 标签 生效 。 比 如 在 Visualize 标签 页 钉 住 一 个 过 滤器 ， 然 后 切换 到 
Discover 或 者 Dashboard 标签 页 ， 过 滤器 依然 还 在 。 注 意 : 如 果 你 钉 住 了 过 
滤器 ， 然 后 发 现 检索 结果 为 室 ， 注 意 查看 当前 标签 页 "EM 式 是 不 是 跟 过 滤 
器 匹配 。 

e 过 滤器 反 转 医 罩 点 击 这 个 图 标 反 转 过 滤器 。 默 认 情 况 下 ， 过 滤器 都 是 包含 型 ， 

显示 为 绿色 ， 只 有 匹配 过 滤 条 件 的 结果 才 会 显示 。 反 转 成 排除 型 过 滤器 后 ， 显 
示 的 是 不 匹配 过 滤器 dis ANLE 

。 移 除 过 滤器 国有 点击 这 个 图 标 删 除 过 滤器 

。 自 定义 过 滤器 点击 这 个 图 标 会 打开 一 个 文本 编辑 框 。 编 辑 框 内 可 以 修改 
JSON 形式 的 过 滤器 内 容 ， 并 起 一 个 alias 别名 : JSON 中 可 以 灵活 应 用 
bool query 组 合 各 种 should ^ must ^ must not 和 条件。 一 个 用 

should 表达 的 OR 关系 过 滤 如 下 : 


"EOD ST 
"should": [ 
{ 
"term": { 
"geoip.country_name.raw": "Canada" 
} 
ty 
{ 
"term": { 
"geoip.country_name.raw": "China" 
} 
} 
] 
} 


一 执行 上 面 的 某 个 操作 ， 点 击 Actions 按钮 ， 然 后 再 执 


ex 


想 要 对 当前 页 所 有 过 渡 器 
行 操 作 即 可 。 


查看 文档 数据 


当 你 提交 一 个 搜索 请 求 ， 最 近 的 500 个 搜索 结果 会 显示 在 文档 表格 里 。 你 可 以 在 
Advanced Settings 里 通过 discover:sampleSize 属性 配置 表格 里 具体 的 文档 
数量 。 默 认 的 ， 表 格 会 显示 当前 选择 的 索引 模式 中 定义 的 时 间 字 段 内 容 (转换 成 本 地 
时 区 ) 以 及 _source 文档 。 你 可 以 从 字段 列表 添加 字段 到 文档 表格 。 还 可 以 用 表 
格 里 包含 的 任意 已 建 索引 的 字段 来 排序 列 出 的 文档 。 


要 查看 一 个 文档 的 字段 数据 ， 点 击 表格 第 一 列 (通常 都 是 时 间 ) 文 档 内 容 左 侧 的 


Expand 按钮 P 。Kibana 从 Elasticsearch 读 取 数 据 然后 在 表格 中 显示 文档 字 
段 。 这 个 表格 每 行 是 一 个 字段 的 名 字 、 过 滤器 按钮 和 字段 的 值 。 


Time _source 


~ April 13th 2017, 22:44:03.388 index: logstash-2017.04.13 @timestamp: April 13th 2017, 22:44:03.388 ip: 107.122. 
180.120 extension: jpg response: 200 geo.coordinates: { "lat": 39.90415167, “lo 
n": -74.74954917 } geo.src: MY geo.dest: US geo.srcdest: MY:US @tags: success, i 
nfo utc_time: April 13th 2017, 22:44:03.388 referer: http://twitter.com/warning/rob 
ert-satcher agent: Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gec 


View surrounding documents View single document 





Table JSON 





(message Q Q m æ 107.122.180.120 - - [2017-04-13T20:44:03.388Z] "GET /uploads/shan 
non-walker.jpg HTTP/1.1" 200 8887 "-" "Mozilla/5.0 (X11; Linux i6 
86) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Saf 
ari/534.24" 

@tags Q Q [D * success, info 


1. 要 查看 原始 JSON 文档 (格式 美化 过 的 )， 点 击 JSON 标签 。 

2. 要 在 单独 的 页 面 上 查看 文档 内 容 ， 点 击 链接 。 你 可 以 添加 书签 或 者 分 享 这 个 链 
接 ， 以 直接 访问 这 条 特定 文档 。 

3. 收回 文档 细节 ， 点 击 Collapse #42 Y o 

4. To toggle a particular field’s column in the Documents table, click the [D 
Toggle column in table button. 


文档 列表 排 友 

你 可 以 用 任意 已 建 索引 的 字段 排序 文档 表格 中 的 数据 。 如 果 当 前 索引 模式 配置 了 时 
间 字 段 ， 默 认 会 使 用 该 字段 倒序 排列 文档 。 

要 改变 排序 方式 : 


e 点击 想 要 用 来 排序 的 字段 名 。 能 用 来 排序 的 字段 在 字段 名 右 侧 都 有 一 个 排序 按 
钮 。 再 次 点 击 字 段 名 ， 就 会 反 向 调整 排序 方式 。 


给 文档 表格 添加 字段 列 

默认 的 ， 文 档 表 格 会 显示 当前 选择 的 索引 模式 中 定义 的 时 间 字 段 内 容 (转换 成 本 地 时 
区 ) 以 及 _source 文档 。 你 可 以 从 字段 列表 添加 字段 到 文档 表格 。 

要 添加 字段 列 到 文档 表格 : 


1. 从 字段 列表 中 添加 一 列 ， 移 动 鼠 标 到 字段 列表 的 字段 上 ， 点 击 它 的 add 按钮 
2， 从 文档 的 字段 数据 添加 一 列 ， 展 开 对 应 的 文档 后 点 击 字段 的 四 Toggle 


column in table 按钮 


添加 的 字段 会 替换 掉 文 档 表格 里 的 source 列 。 同 时 还 会 显示 在 字段 列表 顶部 的 
Selected Fields 区 域 里 。 


要 重 排 表格 中 的 字段 列 ， 移 动 鼠 标 到 你 要 移动 的 列 顶 部 ， 点 击 移动 过 按钮 。 


Time geo.src geo.dest X response 
~ October 21st 2016, 16:36:00.038 VN rom 404. 


从 文档 表格 删除 字段 列 
要 从 文档 表格 删除 字段 列 : 


1. 移动 筷 标 到 字段 列表 的 selected Fields 区 域 里 你 想 要 移 除 的 字段 上 ， 然 
后 点 击 它 的 remove 1x42 * » 
2. 重复 操作 直到 你 移 除 完 所 有 你 想 移 除 的 字段 。 


查看 字段 数据 统计 


从 字段 列表 ， 你 可 以 看 到 文档 表格 里 有 多 少数 据 包 含 了 这 个 字段 ， 排 名 前 5 的 4 
什么 ， 以 及 包含 各 个 值 的 文档 的 占 比 。 


E 
hs 


要 查看 字段 数据 统计 ， 在 字段 列表 中 点 击 对 应 的 字段 名 即 可 。 
t machine.os — [3 


Quick Count @ 
( 436 /466 records ) 


ios QQ 
win xp QQ 
win 7 QQ 
win 8 QQ 
Osx QQ 
| [859 


要 基于 这 个 字段 创建 可 视 化 ， 点 击 字 段 统 计 下 方 的 Visualize 按钮 。 
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各 Visualize 功能 


Visualize 标签 页 用 来 设计 可 视 化 。 你 可 以 保存 可 视 化 ， 以 后 再 用 ， 或 者 加 载 合并 到 
dashboard 里 。 一 个 可 视 化 可 以 基于 以 下 几 种 数据 源 类 型 : 

e 一 个 新 的 交互 式 搜 索 

e 一 个 已 保存 的 搜索 

e 一 个 已 保存 的 可 视 化 


可 视 化 是 基于 Elasticsearch 1.0 4] 4.89 7€ & (aggregation) 特性 。 


创建 一 个 新 可 视 化 


要 开始 一 个 Create New Visualization 向 导 ， 点 击 页 面 左 侧 边 栏 的 Visualize 标 
签 。 如 果 你 已 经 在 浏览 一 个 可 视 化 了 ， 你 可 以 在 顶部 菜单 栏 里 点 击 New 选项 1 向 
导 会 引导 你 继续 以 下 几 步 : 


$1: 选择 可 视 化 类 型 
在 New Visualization 向 导 起 始 页 可 以 选择 以 下 一 个 可 视 化 类 型 : 


类 型 用 途 
Area chart 用 区 块 图 来 可 视 化 多 个 不 同 序列 的 总 体 贡 献 。 


用 数据 表 来 显示 聚合 的 原始 数据 。 其 他 可 视 化 可 以 通过 点 击 底 
部 的 方式 显示 数据 表 。 


Line chart 用 折线 图 来 比较 不 同 序 列 。 


Markdown 用 Markdown 显示 自 定 义 格 式 的 信息 或 和 你 仪表 盘 有 关 的 用 法 
widget 说 明 o 


Data table 


Metric 用 指标 可 视 化 在 你 仪表 盘 上 显示 单个 数字 。 
Pie chart 用 饼 图 来 显示 每 个 来 源 对 总 体 的 贡献 。 
Tile map 用 瓦 片 地 图 将 聚合 结果 和 经 纬度 联系 起 来 。 


Timeseries 计算 和 展示 多 个 时 间 序 列 数据 。 


Vertical bar 用 垂直 条 形 图 作为 一 个 通用 图 形 。 
chart 


你 也 可 以 加 载 一 个 你 之 前 创建 好 保存 下 来 的 可 视 化 。 已 存 可 视 化 选择 器 包括 一 个 文 
on 来 过 滤 可 视 化 名 称 ， 以 及 一 个 指向 对 象 编辑 器 (Object Editor) 的 链接 ， 可 
义 通过 Settings > Edit Saved Objects 来 管理 已 存 的 可 视 化 。 


如 果 你 的 新 可 视 化 是 一 个 Markdown 或 Timeseries 挂件 ， 会 直接 进入 配置 界面 。 
其 他 的 可 视 化 类 型 ， 选 择 后 都 会 转 到 数据 源 选择 。 


第 2 步 : 选择 数据 源 


你 可 以 选择 新 建 或 者 读 取 一 个 已 保存 的 搜索 ， 作 为 你 en 。 搜 索 是 和 一 
个 或 者 一 系列 索引 相关 联 的 。 如 果 你 选择 了 在 一 个 配置 了 多 个 索引 的 系统 上 开始 你 
的 新 搜索 ， 从 可 视 化 编辑 器 的 下 拉 菜 单 里 选 eas 


当 你 从 一 个 已 保存 的 搜索 开始 创建 并 保存 好 了 可 视 化 ， 这 个 搜索 就 绑 定 在 这 个 可 视 
化 上 上。 如果 你 修改 了 搜索 ， 对 应 的 可 视 化 也 会 自动 更 新 。 

第 3 步 : 可 视 化 编辑 器 

可 视 化 编辑 器 用 来 配置 编辑 可 视 化 。 它 有 下 面 几 个 主要 元 素 : 


1. 工具 栏 (Toolbar) 
2. KW # $$ (Aggregation Builder) 
3. 预览 画布 (Preview Canvas) 


visualize fi& 





New Save Load Share Refresh © Last 2 years 


kibana . ES 
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Discover 


Visualize Data Options [ES 5.000 
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Dashboard metrics 
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ET uud buckets 4,000 
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Dev Tools 8 cp 
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„ 3000 
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metric: Count n 2,000 
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Custom Label 1,000 
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LAR 


上 有 一 个 用 户 交 互 式 数据 搜索 的 搜索 框 ， 用 来 保存 和 加 载 可 视 化 。 因 为 可 视 
a 搜索 栏 会 变 成 灰色 。 要 编辑 搜索 ， 双 击 搜索 框 ， 用 编辑 后 
的 版 本 替换 已 保存 搜索 。 


搜索 框 右 侧 的 工具 栏 有 一 系列 按钮 ， 用 于 创建 新 可 视 化 ， 保 存 当 前 可 视 化 ， 加 载 一 
个 已 有 可 视 化 ， 分 享 或 内 齿 可 视 化 ， 和 刷新 当前 可 视 化 的 数据 。 


RA CES 


用 页 面 左 侧 的 聚合 构建 器 配置 你 的 可 视 化 要 用 的 metric fe bucket RF » M 
(Buckets) 的 效果 类 似 于 SQL GROUP BY 语句 。 想 更 详细 的 了 解 聚合 ， 阅 读 
Elasticsearch aggregations reference ° 


在 条 带 图 或 者 折线 图 可 视 化 里 ， 用 metrics 做 Y 丫 轴 ， 然 后 buckets fk X $h » KA AM 
E > UR RD o EAE > metrics 用 来 做 分 片 的 大 小 ，buckets 做 分 片 的 
数量 。 
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为 你 的 可 视 化 Y 轴 选 一 个 metric RS > &,4& count, average, sum, min, max, or 
cardinality (unique count). 为 你 的 可 视 化 X 轴 ， 条 带 凑 色 ， 以 及 行 / 列 的 区 分 选 一 个 
bucket 聚会， 常见 的 有 date histogram, range, terms, filters, 和 significant terms ° 


你 可 以 设置 buckets 执行 的 顺序 。 在 Elasticsearch 里 ， 第 一 个 聚合 决定 了 后 续 聚 
合 的 数据 集 。 下 面 例 子 演示 一 个 网 页 访问 量 前 五 名 的 文件 后 组 名 统计 的 时 间 条 带 
A o 


要 看 所 有 相同 后 级 名 的 ， 设 置 顺序 如 下 : 


1. Color :后 级 名 的 Terms 聚合 
2. X-Axis : Qtimestamp “Hl % # A 


Elasticsearch 收集 记录 ， 算 出 前 5 名 后 级 名 ， 然 后 为 每 个 后 组 名 创建 一 个 时 间 条 带 
A e 


要 看 每 个 小 时 的 前 5 名 后 级 名 情况 ， 设 置 顺序 如 下 : 


1. X-Axis : @timestamp 的 时 间 条 带 图 ( 1 小 时 间隔 ) 
2. Color :后 级 名 的 Terms RA 


这 次 ，Elasticsearch 会 从 所 有 记录 里 创建 一 个 时 间 条 带 图 ， 然 后 在 每 个 桶 内 ， 分 组 
(本 例 中 就 是 一 个 小 时 的 间隔 ) 计 算出 前 5 名 的 后 级 名 。 


记 住 ， 每 个 后 续 的 桶 ， 都 是 从 前 一 个 的 桶 里 分 割 数 据 。 
要 在 预览 画布 (preview canvas) 上 演 染 可 视 化 ， 点 击 聚合 构建 器 底部 的 Apply 按 
$H o 
预览 画布 (canvas) 


预览 canvas 上 显示 你 定义 在 聚合 构建 器 里 的 可 视 化 的 预览 效果 。 要 刷新 可 视 化 预 
览 ， 点 击 工 具 栏 里 的 Refresh 。 


区 块 图 


这 个 图 的 Y 轴 是 数值 维度 。 该 维度 有 以 下 聚合 可 用 : 


e Count count 聚合 返回 选中 索引 模式 中 元 素 的 原始 计数 。 

e Average 这 个 聚合 返回 一 个 数值 字段 的 average 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Sum sum 聚合 返回 一 个 数值 字段 的 总 和 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Min min 有 聚合 返回 一 个 数值 字段 的 最 小 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Max max 聚合 返回 一 个 数值 字段 的 最 大 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Unique Count cardinality 聚合 返回 一 个 字段 的 去 重 数据 值 。 从 下 拉 菜 单 选择 一 
个 字段 。 

e Standard Deviation extended stats 聚合 返回 一 个 数值 字段 数据 的 标准 差 。 从 
下 拉 菜 单 选 择 一 个 字段 。 

e Percentile percentile 聚合 返回 一 个 数值 字段 中 值 的 百分比 分 布 。 从 下 拉 菜 单 选 
择 一 个 字段 ， 然 后 在 Percentiles 框 内 指定 范围 。 点 击 X 移 除 一 个 百分比 框 ， 
点 击 +Add 添加 一 个 百分比 框 。 

e Percentile Rank percentile ranks 聚合 返回 一 个 数值 字段 中 你 指定 值 的 百 分 位 
排名 。 从 下 拉 菜 单 选择 一 个 字段 ， 然 后 在 Values 框 内 指定 一 到 多 个 百 分 位 排 
名 值 。 点 击 义 移 除 一 个 百分比 框 ， 点 击 +Add 添加 一 个 数值 框 。 


你 可 以 点 击 + Add Aggregation 按键 添加 一 个 聚合 。 
buckets 聚合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 


图 形 的 X 轴 是 buckets 维度 。 你 可 以 为 X 轴 定 义 buckets， 同 样 还 可 以 为 图 片上 的 
TAER” RATZI A A ZL buckets。 


该 图 形 的 X 轴 支 持 以 下 聚合 。 点 击 每 个 聚合 的 链接 查看 该 聚合 的 Elasticsearch È 
方 文档 。 


e Date Histogram date histogram 基于 数值 字段 创建 ， 由 时 间 组 织 起 来 。 你 可 以 
指定 时 间 片 的 间隔 ， 单 位 包括 秒 ， 分 ， 小 时 ， 天 ， 星 期 月, 年。 

e Histogram 标准 histogram 基于 数值 字段 创建 。 为 这 个 字段 指定 一 个 整数 间 
隔 。 勾 选 Show empty buckets 让 直方 图 中 包含 空 的 间隔 。 

e Range 通过 range 有 聚合 。 你 可 以 为 一 个 数值 字段 指定 一 系列 区 间 。 点 击 Add 
Range 添加 一 对 区 间 端 点 。 点 击 红色 (x) 符号 移 除 一 个 区 间 。 

e Date Range date range 聚合 计算 你 指定 的 时 间 区 间 内 的 值 。 你 可 以 使 用 date 


math 表达 式 指定 区 间 。 点 击 Add Range 添加 新 的 区 间 端 点 。 点 击 红色 (I) 符 
号 移 除 区 间 。 

e |Pv4 Range IPv4 range 聚合 用 来 指定 IPv4 地 址 的 区 间 。 点 击 Add Range 7 
加 新 的 区 间 端 点 。 点 击 红色 (/) 符号 移 除 区 间 。 

e Terms terms 聚合 允许 你 指定 展示 一 个 字段 的 首尾 几 个 元 素 ， 排 序 方式 可 以 是 
计数 或 者 其 他 自 定义 的 metric 。 

e Filters 你 可 以 为 数据 指定 一 组 filters。 你 可 以 用 query string > 35, T 47] JSON 
格式 来 指定 过 滤器 ， 就 像 在 Discover 页 的 搜索 栏 里 一 样 。 点 击 Add Filter 添 
加 下 一 个 过 滤器 。 


e Significant Terms 展示 实验 性 的 significant terms 聚合 的 结果 。 


一 旦 你 定义 好 了 一 个 X 轴 聚 合 。 你 可 以 继续 定义 子 聚合 来 完善 可 视 化 效果 。 点 击 十 
Add Sub Aggregation 添加 子 聚 合 ， 然 后 选择 Split Area 或 者 Split Chart > 4G 
从 类 型 菜单 中 选择 一 个 子 聚 合 。 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 你 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 聚合 的 
优先 级 。 上 比如 ， 一 个 事件 计数 的 日 期 图 ， 可 以 按照 时 序 显 示 ， 你 也 可 以 提升 事件 聚 
合 的 优先 级 ， 首 先 显示 最 活跃 的 几 天 。 时 序 图 用 来 显示 事件 随 着 时 间 变 化 的 趋势 ， 
而 按照 活跃 时 间 排 序 则 可 以 揭示 你 数据 中 的 部 分 异常 值 。 


Kibana 4.5 以 后 新 增 了 两 个 呼唤 已 久 的 功能 : 在 Custom Label 里 填写 自 定 义 字符 
串 ， 就 可 以 修改 显示 的 标签 文字 。 而 在 具体 标签 值 旁 边 的 颜色 上 点 击 ， 可 以 打开 产 
色 选 择 器 ， 自 定义 自己 的 可 视 化 效果 的 颜色 。 


@ Unique count of speaker 
00000000 
oeoo00000 
0000000 
© 00000 
0000000 

D000 


你 可 以 点 击 Advanced 链接 显示 更 多 有 关 和 聚合 的 自 定义 参数 : 


e Exclude Pattern 指定 一 个 从 结果 集中 排除 掉 的 模式 。 


~ 


Exclude Pattern Flags 排除 模式 的 Java flags 标准 集 。 

Include Pattern 指定 一 个 从 结果 集中 要 包含 的 模式 。 

Include Pattern Flags 包含 模式 的 Java flags 标准 集 。 

JSON Input 一 个 用 来 添加 JSON 格式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定 
义 中 ， 格 式 如 下 例 : 


"script" : "doc['grade'].value * 1.2" } 


Elasticsearch 1.4.3 及 以 后 版 本 ， 这 个 函数 需要 你 开启 dynamic Groovy 
scripting ° 


些 参数 是 否 可 用 ， 依 赖 于 你 选择 的 聚合 函数 。 


选择 view options 更 改 表格 中 如 下 方面 : 


Chart Mode 当 你 为 图 形 定 义 了 多 个 站 轴 时 ， 你 可 以 用 该 下 拉 菜 单 定义 聚合 如 
何 显 示 在 图 形 上 


o stacked RA RIKK E mE MR o 

o overlap we ERE ENA RA FB MAR o 
o wiggle 聚合 结果 显示 成 AAA 效果 。 

o a 示 每 个 聚合 在 总 数 中 的 百 分 值 。 
o silhouette 显 aes 中 间 线 的 方差 。 


选 框 可 以 用 来 控制 以 下 行为 : 


Smooth Lines 义 选 该 项 平滑 数据 点 之 间 的 折线 成 曲线 。 

Set Y-Axis Extents 勾 选 该 项 ， 然 后 在 y-max 和 y-min 框 里 输入 数值 限定 Y 轴 
为 指定 数值 。 

Scale Y-Axis to Data Bounds 默认 的 Y 轴 长 度 为 0 到 数据 集 的 最 大 值 。 勾 选 该 
项 改变 Y 轴 的 最 大 和 最 小 值 为 数据 集 的 返回 值 。 

Show Tooltip 勾 选 该 项 显示 工具 栏 。 

Show Legend 句 选 该 项 在 图 形 右 侧 显 示 图 例 。 


数据 表格 


e Count count 聚合 返回 选中 索引 模式 中 元 素 的 原始 计数 。 

e Average 这 个 聚合 返回 一 个 数值 字段 的 average 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Sum sum 聚合 返回 一 个 数值 字段 的 总 和 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Min min 有 聚合 返回 一 个 数值 字段 的 最 小 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Max max 聚合 返回 一 个 数值 字段 的 最 大 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Unique Count cardinality 有 聚合 返回 一 个 字段 的 去 重 数据 值 。 从 下 拉 菜 单 选择 一 
个 字段 。 

e Standard Deviation extended stats 聚合 返回 一 个 数值 字段 数据 的 标准 差 。 从 
下 拉 菜 单 选 择 一 个 字段 。 

e Percentile percentile 聚合 返回 一 个 数值 字段 中 值 的 百分比 分 布 。 从 下 拉 菜 单 选 
择 一 个 字段 ， 然 后 在 Percentiles 框 内 指定 范围 。 点 击 X 移 除 一 个 百分比 框 ， 
点 击 + Add Percent 添加 一 个 百分比 框 。 

e Percentile Rank percentile ranks 聚合 返回 一 个 数值 字段 中 你 指定 值 的 百 分 位 
排名 。 从 下 拉 菜 单 选择 一 个 字段 ， 然 后 在 Values 框 内 指定 一 到 多 个 百 分 位 排 
名 值 。 点 击 义 移 除 一 个 百分比 框 ， 点 击 +Add 添加 一 个 数值 框 。 


你 可 以 点 击 + Add Aggregation 按键 添加 一 个 聚合 。 


数据 表格 的 每 行 ， 叫 做 buckets。 你 可 以 定义 buckets 来 切割 表格 成 行 ， 或 者 切割 
表格 成 另 一 个 表格 。 


每 个 bucket 类 型 都 支持 以 下 聚合 : 


e Date Histogram date histogram 基于 数值 字段 创建 ， 由 时 间 组 织 起 来 。 你 可 以 
指定 时 间 片 的 间隔 ， 单 位 包括 秒 ， 分 ， 小 时 ， 天 ， 星 期 月， 年 。 

e Histogram 标准 histogram 基于 数值 字段 创建 。 为 这 个 字段 指定 一 个 整数 间 
f& » 4% Show empty buckets 让 直方 图 中 包含 空 的 间隔 。 

e Range 通过 range 聚合 。 你 可 以 为 一 个 数值 字段 指定 一 系列 区 间 。 点 击 Add 
Range 添加 一 堆 区 间 端 点 。 点 击 红色 (x) 符号 移 除 一 个 区 间 。 

e Date Range date range 聚合 计算 你 指定 的 时 间 区 间 内 的 值 。 你 可 以 使 用 date 
math 表达 式 指 定 区 间 。 点 击 Add Range 添加 新 的 区 间 端 点 。 点 击 红 色 (I) 符 
号 移 除 区 间 。 

e |Pv4 Range IPv4 range 有 聚合 用 来 指定 IPv4 地 址 的 区 间 。 点 击 Add Range 7 
加 新 的 区 间 端 点 。 点 击 红色 D) 符号 移 除 区 间 。 


e Terms terms 聚合 允许 你 指定 展示 一 个 字段 的 首尾 几 个 元 素 ， 排 序 方式 可 以 是 
计数 或 者 其 他 自 定义 的 metric 。 

e Filters 你 可 以 为 数据 指定 一 组 filters。 你 可 以 用 query string > 35 T 471] JSON 
格式 来 指定 过 滤器 ， 就 像 在 Discover 页 的 搜索 栏 里 一 样 。 点 击 Add Filter 添 
加 下 一 个 过 滤器 。 

e Significant Terms 展示 实验 性 的 significant terms 聚合 的 结果 。 

e Geohash geohash 聚合 显示 基于 地 理 坐 标的 点 。 


一 旦 你 定义 好 了 一 个 X 轴 聚 合 。 你 可 以 继续 定义 子 聚合 来 完善 可 视 化 效果 。 点 击 十 
Add Sub Aggregation 添加 子 聚 合 ， 然 后 选择 Split Area 或 者 Split Chart > 42 
从 类 型 菜单 中 选择 一 个 子 聚 合 。 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 你 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 有 聚合 的 
优先 级 。 


你 可 以 点 击 Advanced 链接 显示 更 多 有 关 聚 合 的 自 定义 参数 : 


e Exclude Pattern 指定 一 个 从 结果 集中 排除 掉 的 模式 。 

e Exclude Pattern Flags 排除 模式 的 Java flags 标准 集 。 

e Include Pattern 指定 一 个 从 结果 集中 要 包含 的 模式 。 

e Include Pattern Flags 包含 模式 的 Java flags 标准 集 。 

e JSON Input 一 个 用 来 添加 ISON 格式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定 
义 中 ， 格 式 如 下 例 : 


{ "script" : "doc['grade'].value * 1.2" } 
WE 


Elasticsearch 1.4.3 及 以 后 版 本 ， 这 个 函数 需要 你 开 尼 dynamic Groovy 


scripting ° 
这 些 参数 是 否 可 用 ， 依 赖 于 你 选择 的 聚合 函数 。 
选择 view options 更 改 表格 中 如 下 方面 : 

e Per Page 这 个 输入 框 控制 表格 的 翻 页 。 默 认 值 是 每 页 10 fT o 
多 选 框 用 来 控制 以 下 行为 : 


e Show metrics for every bucket/level 勾 选 此 项 用 以 显示 每 个 bucket 聚合 的 中 


la] 25 Ro 
e Show partial rows 义 选 此 项 显示 没有 数据 的 行 。 


Lines Charts 


这 个 图 的 Y 轴 是 数值 维度 。 该 维度 有 以 下 聚合 可 用 : 


e Count count 聚合 返回 选中 索引 模式 中 元 素 的 原始 计数 。 

e Average 这 个 聚合 返回 一 个 数值 字段 的 average 。 从 下 拉 菜 单 选择 一 个 字段 。 
e Sum sum 聚合 返回 一 个 数值 字段 的 总 和 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Min min 有 聚合 返回 一 个 数值 字段 的 最 小 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Max max 聚合 返回 一 个 数值 字段 的 最 大 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Unique Count cardinality 聚合 返回 一 个 字段 的 去 重 数据 值 。 从 下 拉 菜 单 选择 一 
个 字段 。 

Standard Deviation extended stats 聚合 返回 一 个 数值 字段 数据 的 标准 差 。 从 
下 拉 菜 单 选择 一 个 字段 。 

Percentile percentile 聚合 返回 一 个 数值 字段 中 值 的 百分比 分 布 。 从 下 拉 菜 单 选 
择 一 个 字段 ， 然 后 在 Percentiles 框 内 指定 范围 。 点 击 X 移 除 一 个 百分比 框 ， 
点 击 +Add Percent 添加 一 个 百分比 框 。 

Percentile Rank percentile ranks 聚合 返回 一 个 数值 字段 中 你 指定 值 的 百 分 位 
排名 。 从 下 拉 菜 单 选择 一 个 字段 ， 然 后 在 Values 框 内 指定 一 到 多 个 百 分 位 排 
名 值 。 点 击 义 移 除 一 个 百分比 框 ， 点 击 +Add 添加 一 个 数值 框 。 


你 可 以 点 击 + Add Aggregation 按键 添加 一 个 聚合 。 
buckets 聚合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 


在 你 选 定 一 个 buckets 聚合 之 前 ， 先 指定 你 是 要 切割 单个 图 的 分 片 ， 还 是 切割 成 多 
个 图 形 。 多 图 切 分 必须 在 其 他 任何 聚合 之 前 要 运行 。 如 果 你 切 分 图 形 ， 你 可 以 选择 
切 分 结果 是 展示 成 行 还 是 列 的 形式 ， 点 击 Rows | Columns 选择 器 即 可 。 


图 形 的 X dj buckets 维度 。 你 可 以 为 X 轴 定 义 buckets， 同 样 还 可 以 为 图 片上 的 
分 片区 域 ， 或 者 分 割 的 图 片 定 义 buckets 。 


该 图 形 的 X 轴 支 持 以 下 聚合 。 点 击 每 个 聚合 的 链接 查看 该 聚合 的 Elasticsearch E 
方 文档 。 


e Date Histogram date histogram 基于 数值 字段 创建 ， 由 时 间 组 织 起 来 。 你 可 以 
间 定 时 间 片 的 间隔 ， 单 位 包括 秒 ， 分 ， 小 时 ， 天 ， 星 期 ， 月 ， 年 。 

e Histogram 标准 histogram 基于 数值 字段 创建 。 为 这 个 字段 指定 一 个 整数 间 
ha » 4% Show empty buckets 让 直方 图 中 包含 空 的 间隔 。 


e Range 通过 range 聚合 。 你 可 以 为 一 个 数值 字段 指定 一 系列 区 间 。 点 击 Add 
Range 添加 一 堆 区 间 端 点 。 点 击 红色 (x) 符号 移 除 一 个 区 间 。 

e Date Range date range 聚合 计算 你 指定 的 时 间 区 间 内 的 值 。 你 可 以 使 用 date 
math 表达 式 指 定 区 间 。 点 击 Add Range 添加 新 的 区 间 端 点 。 点 击 红 色 (I) 符 
号 移 除 区 间 。 

e IPv4 Range IPv4 range 有 聚合 用 来 指定 IPv4 地 址 的 区 间 。 点击 Add Range 7 
加 新 的 区 间 端 点 。 点 击 红色 (I) 符号 移 除 区 间 。 

e Terms terms 聚合 允许 你 指定 展示 一 个 字段 的 首尾 几 个 元 素 ， 排 序 方式 可 以 是 
计数 或 者 其 他 自 定义 的 metric » 

e Filters 你 可 以 为 数据 指定 一 组 filters。 你 可 以 用 query string * 4 T 47] JSON 
格式 来 指定 过 滤器 ， 就 像 在 Discover 页 的 搜索 栏 里 一 样 。 点 击 Add Filter 7& 
加 下 一 个 过 滤器 。 


e Significant Terms 展示 实验 性 的 significant terms 聚合 的 结果 。 


一 旦 你 定义 好 了 一 个 X 轴 聚 合 。 你 可 以 继续 定义 子 聚 合 来 完善 可 视 化 效果 。 点 击 十 
Add Sub Aggregation 添加 子 聚合 ， 然 后 选择 Split Area 或 者 Split Chart > AG 
从 类 型 菜单 中 选择 一 个 子 聚 合 。 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 你 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 聚合 的 
优先 级 。 


你 可 以 点 击 Advanced 链接 显示 更 多 有 关 聚 合 的 自 定义 参数 : 


e Exclude Pattern 指定 一 个 从 结果 集中 排除 掉 的 模式 。 

e Exclude Pattern Flags 排除 模式 的 Java flags 标准 集 。 

e Include Pattern 指定 一 个 从 结果 集中 要 包含 的 模式 。 

e Include Pattern Flags 包含 模式 的 Java flags 标准 集 。 

e JSON Input 一 个 用 来 添加 ISON 格式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定 
义 中 ， 格 式 如 下 例 : 


~ 


"script" : "doc['grade'].value * 1.2" } 


Elasticsearch 1.4.3 及 以 后 版 本 ， 这 个 函数 需要 你 开 尼 dynamic Groovy 
scripting ° 


这 些 参 数 是 否 可 用 ， 依 赖 于 你 选择 的 聚合 函数 。 


多 选 框 可 以 用 来 控制 以 下 行为 : 


e YY 轴 比 例 可 以 给 图 形 的 Y 轴 选 择 linear, log X square root 三 种 比例 。 你 可 


以 给 指数 变化 的 数据 采用 log 骂 数 比例 显示 ， 上 比如 复 利 图 表 ; 也 可 以 用 平方 根 
(square root) 比 例 显示 数值 变化 差异 极 大 的 数据 集 。 这 种 可 变性 本 身 也 算 变 量 
的 一 种 的 数据 ， 又 叫 异 方差 数据 。 上 比如 ， 身 高 和 体重 的 数据 集 ， 在 较 矮 的 区 间 
变化 是 很 小 的 ， 但 是 在 较 高 另 一 个 区 间 ， 数 据 集 就 是 异 方差 式 的 。 

Smooth Lines 勾 选 该 项 ， 将 图 中 的 数据 点 用 平滑 曲线 连接 。 注 意 : 平滑 曲线 在 
高 峰 低谷 处 给 人 的 印象 与 实际 值 有 较 大 偏差 。 

Show Connecting Lines 义 选 该 项 ， 将 图 中 的 数据 点 用 折线 连接 。 

Show Circles 义 选 该 项 ， 将 图 中 的 数据 点 绘制 成 一 个 小 圆圈 。 

Current time marker 对 时 序数 据 ， 勾 选 该 项 可 以 在 当前 时 刻 位 置 标记 一 条 红 
Set Y-Axis Extents 义 选 该 项 ， 然 后 在 y-max 和 y-min 框 里 输入 数值 限定 Y 轴 
为 指定 数值 。 

Show Tooltip 勾 选 该 项 显示 工具 栏 。 

Show Legend 勾 选 该 项 在 图 形 右 侧 显示 图 例 。 

Scale Y-Axis to Data Bounds 默认 的 Y 轴 长 度 为 0 到 数据 集 的 最 大 值 。 义 选 该 
项 改变 YY 轴 的 最 大 和 最 小 值 为 数据 集 的 返回 值 。 


更 新 选项 后 ， 点 击 绿色 Apply changes 按钮 更 新 你 的 可 视 化 界面 ， 或 者 灰色 
Discard changes 按钮 保持 原状 。 


气泡 图 (Bubble Charts) 


RON > 


以 下 步骤 ， 可 以 转换 折线 图 成 气泡 图 : 


7j Y 44.27 Add Metrics 然后 选择 Dot Size ° 

从 下 拉 框 里 选择 一 个 metric RS BHR » 

. 在 Options 标签 里 ， 去 掉 Show Connecting Lines 的 勾 选 
点 击 Apply changes 按钮 。 


Markdown 挂件 


Markdown 挂件 是 一 个 存放 GitHub 风格 Markdown A 449 3: AWE ° Kibana 2€ # 
你 输入 的 文本 ， 然 后 在 仪表 盘 上 显示 泻 染 结果 。 你 可 以 点 击 Help 连接 跳 转 到 help 
page 查看 GitHub 风格 Markdown 的 说 明 。 点 击 Apply 在 预览 框 查看 泻 染 效果 ， 
或 者 Discard 回 退 成 上 一 个 版 本 的 内 容 。 


Metric 


metric 可 视 化 为 你 选择 的 聚合 显示 一 个 单独 的 数字 : 


Count count 聚合 返回 选中 索引 模式 中 元 素 的 原始 计数 。 

Average 这 个 聚合 返回 一 个 数值 字段 的 average 。 从 下 拉 菜 单 选择 一 个 字段 。 
Sum sum 聚合 返回 一 个 数值 字段 的 总 和 。 从 下 拉 菜 单 选择 一 个 字段 。 

Min min 聚合 返回 一 个 数值 字段 的 最 小 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

Max max 聚合 返回 一 个 数值 字段 的 最 大 值 。 从 下 拉 菜 单 选 择 一 个 字段 。 
Unique Count cardinality 聚合 返回 一 个 字段 的 去 重 数据 值 。 从 下 拉 菜 单 选择 一 
个 字段 。 

Standard Deviation extended stats 聚合 返回 一 个 数值 字段 数据 的 标准 差 。 从 
下 拉 菜 单 选择 一 个 字段 。 

Percentile percentile 聚合 返回 一 个 数值 字段 中 值 的 百分比 分 布 。 从 下 拉 菜 单 选 
择 一 个 字段 ， 然 后 在 Percentiles 框 内 指定 范围 。 点 击 X 移 除 一 个 百分比 框 ， 
点 击 +Add Percent 添加 一 个 百分比 框 。 

Percentile Rank percentile ranks 聚合 返回 一 个 数值 字段 中 你 指定 值 的 百 
排名 。 从 下 拉 菜 单 选择 一 个 字段 ， 然 后 在 Values 框 内 指定 一 到 多 个 百 分 
A fie RX 移 除 一 个 百分比 框 ， 点 击 +Add 添加 一 个 数值 框 。 


位 排 


你 可 以 点 击 + Add Aggregation 按键 添加 一 个 有 聚合。 你 可 以 点 击 Advanced 链接 
显示 更 多 有 关 有 聚合 的 自 定义 参数 : 


~ 


Exclude Pattern 指定 一 个 从 结果 集中 排除 掉 的 模式 。 

Exclude Pattern Flags 排除 模式 的 Java flags 标准 集 。 

Include Pattern 指定 一 个 从 结果 集中 要 包含 的 模式 。 

Include Pattern Flags 包含 模式 的 Java flags 标准 集 。 

JSON Input 一 个 用 来 添加 ISON 格式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定 
义 中 ， 格 式 如 下 例 : 


"script" : "doc['grade'].value * 1.2" } 


mr trip 
Metric 


Elasticsearch 1.4.3 及 以 后 版 本 ， 这 个 函数 需要 你 开启 dynamic Groovy 
scripting ° 


o 


这 些 参 数 是 否 可 用 ， 依 赖 于 你 选择 的 聚合 函数 


点 击 view options 修改 显示 metric 的 字体 大 小 。 


NA 
t E 
饼 图 的 分 片 大 小 通过 metrics 聚合 定义 。 这 个 维度 可 以 支持 以 下 聚合 : 


e Count count 聚合 返回 选中 索引 模式 中 元 素 的 原始 计数 。 

e Sum sum 聚合 返回 一 个 数值 字段 的 总 和 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Unique Count cardinality 聚合 返回 一 个 字段 的 去 重 数据 值 。 从 下 拉 菜 单 选择 一 
个 字段 。 


buckets 聚合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 


在 你 选 定 一 个 buckets 聚合 之 前 ， 先 指定 你 是 要 切割 单个 图 的 分 片 ， 还 是 切割 成 多 
个 图 形 。 多 图 切 分 必须 在 其 他 任何 聚合 之 前 要 运行 。 如 果 你 切 分 图 形 ， 你 可 以 选择 
切 分 结果 是 展示 成 行 还 是 列 的 形式 ， 点 击 Rows | Columns 选择 器 即 可 。 


你 可 以 为 你 的 饼 图 指定 以 下 任意 bucket RE : 


e Date Histogram date histogram 基于 数值 字段 创建 ， 由 时 间 组 织 起 来 。 你 可 以 
间 定 时 间 片 的 间隔 ， 单 位 包括 秒 ， 人 分， 小时， 天， 星期， 月， 年 。 

e Histogram 标准 histogram 基于 数值 字段 创建 。 为 这 个 字段 指定 一 个 整数 间 
ha » 4% Show empty buckets 让 直方 图 中 包含 空 的 间隔 。 

e Range 通过 range 聚合 。 你 可 以 为 一 个 数值 字段 指定 一 系列 区 间 。 点 击 Add 
Range 添加 一 堆 区 间 端 点 。 点 击 红色 (x) 符号 移 除 一 个 区 间 。 

e Date Range date range 聚合 计算 你 指定 的 时 间 区 间 内 的 值 。 你 可 以 使 用 date 
math 表达 式 指 定 区 间 。 点 击 Add Range 添加 新 的 区 间 端 点 。 点 击 红 色 (I) 符 
号 移 除 区 间 。 

e |Pv4 Range IPv4 range 有 聚合 用 来 指定 IPv4 地 址 的 区 间 。 点 击 Add Range % 
加 新 的 区 间 端 点 。 点 击 红色 (/) 符号 移 除 区 间 。 

e Terms terms 聚合 允许 你 指定 展示 一 个 字段 的 首尾 几 个 元 素 ， 排 序 方式 可 以 是 
计数 或 者 其 他 自 定 义 的 metric ° 

e Filters 你 可 以 为 数据 指定 一 组 filters。 你 可 以 用 query string， 也 可 以 用 JSON 
格式 来 指定 过 滤器 ， 就 像 在 Discover 页 的 搜索 栏 里 一 样 。 点 击 Add Filter 7& 
加 下 一 个 过 滤器 。 


e Significant Terms 展示 实验 性 的 significant terms 聚合 的 结果 。 


一 旦 你 定义 好 了 一 个 X 轴 聚 合 。 你 可 以 继续 定义 子 聚 合 来 完善 可 视 化 效果 。 点 击 十 
Add Sub Aggregation 添加 子 聚合 ， 然 后 选择 Split Area 或 者 Split Chart > AG 
从 类 型 菜单 中 选择 一 个 子 聚 合 。 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 你 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 聚合 的 
优先 级 。 
你 可 以 点 击 Advanced 链接 显示 更 多 有 关 聚 合 的 自 定义 参数 : 


e Exclude Pattern 指定 一 个 从 结果 集中 排除 掉 的 模式 。 

e Exclude Pattern Flags 排除 模式 的 Java flags 标准 集 。 

e Include Pattern 指定 一 个 从 结果 集中 要 包含 的 模式 。 

e Include Pattern Flags 包含 模式 的 Java flags 标准 集 。 

e JSON Input 一 个 用 来 添加 ISON 格式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定 
义 中 ， 格 式 如 下 例 : 


{ "script" : "doc['grade'].value * 1.2" } 


Elasticsearch 1.4.3 及 以 后 版 本 ， 这 个 函数 需要 你 开启 dynamic Groov 
y y 


scripting ° 
这 些 参数 是 否 可 用 ， 依 赖 于 你 选择 的 聚合 函数 。 
选择 view options 更 改 表格 中 如 下 方面 : 


e Donut Display the chart as a sliced ring instead of a sliced pie. 
e Show Tooltip 勾 选 该 项 显示 工具 栏 。 
e Show Legend 勾 选 该 项 在 图 形 右 侧 显 示 图 例 。 
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瓦 片 地 图 显示 一 个 由 圆圈 覆盖 着 的 地 理 区 域 。 这 些 圆圈 则 是 由 你 指定 的 buckets 4 
制 的 。 


瓦 片 地 图 的 默认 metrics 聚合 是 Count 聚合 。 你 可 以 选择 下 列 聚 合 中 的 任意 一 个 作 
A metrics RF : 


e Count count 聚合 返回 选中 索引 模式 中 元 素 的 原始 计数 。 

e Average 这 个 聚合 返回 一 个 数值 字段 的 average 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Sum sum 聚合 返回 一 个 数值 字段 的 总 和 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Min min 有 聚合 返回 一 个 数值 字段 的 最 小 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Max max 聚合 返回 一 个 数值 字段 的 最 大 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Unique Count cardinality 聚合 返回 一 个 字段 的 去 重 数据 值 。 从 下 拉 菜 单 选择 一 
个 字段 。 


buckets 聚合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 

在 你 选择 buckets 聚合 前 ， 指 定 你 是 打算 分 割 图 形 ， 还 是 在 单个 图 形 上 显示 
buckets 为 Geo Coordinates。 儿 图 切割 的 聚合 必须 在 最 先 运行 。 

瓦 片 地 图 使 用 Geohash 聚合 作为 他 们 的 初始 化 聚合 。 从 下 拉 菜 单 中 选择 一 个 坐标 
字段 。Precision 滑动 条 设置 圆圈 在 地 图 上 显示 的 颗粒 度 大 小 。 阅 读 geohash grid 


聚合 的 文档 ， 了 解 每 个 精度 级 别 的 区 域 细 节 。Kibana 4.1 目前 支持 的 最 大 geohash 
长 度 为 7。 
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更 高 的 精度 意味 着 同时 消耗 了 浏览 器 和 ES 集群 更 多 的 内 存 。 


一 旦 你 定义 好 了 一 个 X 轴 聚 合 。 你 可 以 继续 定义 子 聚 合 来 完善 可 视 化 效果 。 点 击 十 
Add Sub Aggregation 添加 子 聚合 ， 然 后 选择 Split Area 或 者 Split Chart > AG 
从 类 型 菜单 中 选择 一 个 子 聚 合 。 


e Date Histogram date histogram 基于 数值 字段 创建 ， 由 时 间 组 织 起 来 。 你 可 以 
指定 时 间 片 的 间隔 ， 单 位 包括 秒 ， 分 ， 小 时 ， 天 ， 星 期 月， 年 。 
e Histogram 标准 histogram 基于 数值 字段 创建 。 为 这 个 字段 指定 一 个 整数 间 


ha » 4% Show empty buckets 让 直方 图 中 包含 空 的 间隔 。 

Range 通过 range 聚合 。 你 可 以 为 一 个 数值 字段 指定 一 系列 区 间 。 点击 Add 
Range 添加 一 堆 区 间 端 点 。 点 击 红色 (x) 符号 移 除 一 个 区 间 。 

Date Range date range 聚合 计算 你 指定 的 时 间 区 间 内 的 值 。 你 可 以 使 用 date 
math 表达 式 指 定 区 间 。 点 击 Add Range 添加 新 的 区 间 端 点 。 点 击 红 色 (I) 符 
号 移 除 区 间 。 

IPv4 Range IPv4 range 聚合 用 来 指定 IPv4 地 址 的 区 间 。 点 击 Add Range 添 
加 新 的 区 间 端点 。 点 击 红色 (/) 符号 移 除 区 间 。 

Terms terms 聚合 允许 你 指定 展示 一 个 字段 的 首尾 几 个 元 素 ， 排 序 方式 可 以 是 
计数 或 者 其 他 自 定义 的 metric 。 

Filters 你 可 以 为 数据 指定 一 组 filters。 你 可 以 用 query string， 也 可 以 用 JSON 
格式 来 指定 过 滤器 ， 就 像 在 Discover 页 的 搜索 栏 里 一 样 。 点 击 Add Filter 添 
加 下 一 个 过 滤器 。 

Significant Terms 展示 实验 性 的 significant terms 聚合 的 结果 。 

Geohash The geohash aggregation displays points based on the geohash 
coordinates. 


你 可 以 点 击 Advanced 链接 显示 更 多 有 关 和 聚合 的 自 定义 参数 : 


Exclude Pattern 指定 一 个 从 结果 集中 排除 掉 的 模式 。 

Exclude Pattern Flags 排除 模式 的 Java flags 标准 集 。 

Include Pattern 指定 一 个 从 结果 集中 要 包含 的 模式 。 

Include Pattern Flags 包含 模式 的 Java flags 标准 集 。 

JSON Input 一 个 用 来 添加 ISON 格式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定 
义 中 ， 格 式 如 下 例 : 


{ "script" : "doc['grade'].value * 1.2" } 


Elasticsearch 1.4.3 及 以 后 版 本 ， 这 个 函数 需要 你 开 尼 dynamic Groovy 
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参数 是 否 可 用 ， 依 赖 于 你 选择 的 聚合 函数 。 


选择 Options 改变 表格 的 如 下 方面 : 


Map type 
从 下 拉 框 选择 下 面 一 个 选项 。 


e Shaded Circle Markers 根据 metric 聚合 的 值 显示 不 同 的 颜色 。 
e Scaled Circle Markers 根据 metric 有 聚合 的 值 显示 不 同 的 大 小 。 
e Shaded Geohash Grid F #274 4% 4% RU 49 AW ET geohash， 根 据 metric % 
合 的 值 显示 不 同 的 颜色 。 
e Heatmap 热力 图 可 以 模糊 化 圆 标 而 且 层 党 显示 磊 色 。 热 力图 本 身 还 有 如 下 选项 
TA: 
o Radius: 设置 单个 热力 图 点 的 大 小 。 
o Blur: 设置 热力 图 点 的 模糊 度 。 
o Maximum zoom: Kibana 的 Tilemap 支持 18 级 缩放 。 该 选项 设置 热力 图 
最 大 强度 下 的 最 高 缩放 级 别 。 
o Minimum opacity: 设置 数据 点 的 不 透明 截止 位 置 。 
o Show Tooltip: 勾 选 该 项 ， 让 鼠标 放 在 数据 点 上 时 显示 该 点 的 数据 。 


Desaturate map tiles 


淡化 地 图 颜色 ， 上 凸显 标记 的 清晰 度 。 


WMS compliant map server 


勾 选 该 项 ， 可 以 配置 使 用 符合 Web Map Service (WMS) 标准 的 其 他 第 三 方 地 图 服 
务 。 需 要 指定 一 下 参数 : 


e WMS url: WMS 地 图 服务 的 URL ; 

e WMS layers: 用 于 可 视 化 的 图 层 列表 ， 喜 号 分 隔 。 每 个 地 图 服务 商都 会 提供 自 
己 的 图 层 。 

e WMS version: 该 服务 商 采 用 的 WMS 版 本 。 

e WMS format: 该 服务 商 使 用 的 图 片 格 式 。 通 常 来 说 是 image/png 或 
image/jpeg ° 

e WMS attribution: 可 选项 。 用 户 自 定义 字符 串 ， 用 来 显示 在 图 表 右 下 角 的 属性 
说 明 。 

e WMS styles: 过 号 分 隔 的 风格 列表 。 每 个 地 图 服务 商都 会 提供 自己 的 风格 选 
项 o 


更 新 选项 后 ， 点 击 绿色 Apply changes 按钮 更 新 你 的 可 视 化 界面 ， 或 者 灰色 
Discard changes 按钮 保持 原状 。 


Navigating the Map 


可 视 化 地 图 就 绪 后 ， 你 可 以 通过 一 下 方式 探索 地 图 : 
e 在 地 图 任意 位 置 点 击 并 按 住 筷 标 后 ， 拖 动 即 可 转移 地 图 中 心 。 按 住所 标 左 键 拖 
搜 绘制 方 框 则 定 区 域 。 
e 点击 Zoom In/Out - 按钮 手动 修改 缩放 级 别 。 
e 点击 Fit Data Bounds 按钮 让 地 图 自动 聚焦 到 至 少 有 一 个 数据 点 的 地 区 。 


e 点 击 Latitude/Longitude Filter F 按钮 ， 然 后 在 地 图 上 拖 搜 绘制 一 个 方 框 ， 
自动 生成 这 个 框 范围 的 经 纬度 过 滤器 。 
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这 个 图 的 Y 轴 是 数值 维度 。 该 维度 有 以 下 聚合 可 用 : 


e Count count 聚合 返回 选中 索引 模式 中 元 素 的 原始 计数 。 

e Average 这 个 聚合 返回 一 个 数值 字段 的 average 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Sum sum 聚合 返回 一 个 数值 字段 的 总 和 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Min min 聚合 返回 一 个 数值 字段 的 最 小 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Max max 聚合 返回 一 个 数值 字段 的 最 大 值 。 从 下 拉 菜 单 选择 一 个 字段 。 

e Unique Count cardinality 聚合 返回 一 个 字段 的 去 重 数据 值 。 从 下 拉 菜 单 选择 一 
个 字段 。 

e Standard Deviation extended stats 聚合 返回 一 个 数值 字段 数据 的 标准 差 。 从 
下 拉 菜 单 选 择 一 个 字段 。 

e Percentile percentile 聚合 返回 一 个 数值 字段 中 值 的 百分比 分 布 。 从 下 拉 菜 单 选 
择 一 个 字段 ， 然 后 在 Percentiles 框 内 指定 范围 。 点 击 X 移 除 一 个 百分比 框 ， 
点 击 + Add Percent 添加 一 个 百分比 框 。 


你 可 以 点 击 + Add Aggregation 按键 添加 一 个 聚合 。 
buckets 聚合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 


在 你 选 定 一 个 buckets 聚合 之 前 ， 先 指定 你 是 要 切割 单个 图 的 分 片 ， 还 是 切割 成 多 
个 图 形 。 多 图 切 分 必须 在 其 他 任何 聚合 之 前 要 运行 。 如 果 你 切 分 图 形 ， 你 可 以 选择 
切 分 结果 是 展示 成 行 还 是 列 的 形式 ， 点 击 Rows | Columns 选择 器 即 可 。 


图 形 的 X dà buckets 维度 。 你 可 以 为 X 轴 定 义 buckets， 同 样 还 可 以 为 图 片上 的 
分 片区 域 ， 或 者 分 割 的 图 片 定 义 buckets 。 


GAGA X 轴 支 持 以 下 聚合 。 点 击 每 个 聚合 的 链接 查看 该 聚合 的 Elasticsearch 官 
方 文档 。 


e Date Histogram date histogram 基于 数值 字段 创建 ， 由 时 间 组 织 起 来 。 你 可 以 
指定 时 间 片 的 间隔 ， 单 位 包括 秒 ， 分 ， 小 时 ， 天 ， 星 期 ， 月 ， 年 。 

e Histogram 标准 histogram 基于 数值 字段 创建 。 为 这 个 字段 指定 一 个 整数 间 
隔 。 勾 选 Show empty buckets 让 直方 图 中 包含 空 的 间隔 。 

e Range 通过 range 聚合 。 你 可 以 为 一 个 数值 字段 指定 一 系列 区 间 。 点 击 Add 
Range 添加 一 堆 区 间 端 点 。 点 击 红 色 (x) 符号 移 除 一 个 区 间 。 

e Terms terms 聚合 允许 你 指定 展示 一 个 字段 的 首尾 几 个 元 素 ， 排 序 方式 可 以 是 


计数 或 者 其 他 自 定义 的 metric » 

e Filters 你 可 以 为 数据 指定 一 组 filters。 你 可 以 用 query string > 35 T 471] JSON 
格式 来 指定 过 滤器 ， 就 像 在 Discover 页 的 搜索 栏 里 一 样 。 点 击 Add Filter 添 
加 下 一 个 过 滤器 。 


e Significant Terms 展示 实验 性 的 significant terms 有 聚合 的 结果 。 


一 旦 你 定义 好 了 一 个 X 轴 聚 合 。 你 可 以 继续 定义 子 聚 合 来 完善 可 视 化 效果 。 点 击 十 
Add Sub Aggregation 添加 子 聚 合 ， 然 后 选择 Split Area 或 者 Split Chart ， 然 后 
从 类 型 菜单 中 选择 一 个 子 聚 合 。 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 你 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 有 聚合 的 
优先 级 。 


你 可 以 点 击 Advanced 链接 显示 更 多 有 关 聚 合 的 自 定义 参数 : 


。 Exclude Pattern 指定 一 个 从 结果 集中 排除 掉 的 模式 。 

e Exclude Pattern Flags 排除 模式 的 Java flags 标准 集 。 

e Include Pattern 指定 一 个 从 结果 集中 要 包含 的 模式 。 

e Include Pattern Flags 包含 模式 的 Java flags 标准 集 。 

e JSON Input 一 个 用 来 添加 ISON 格式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定 
义 中 ， 格 式 如 下 例 : 


~ 


"script" : "doc['grade'].value * 1.2" } 


Elasticsearch 1.4.3 及 以 后 版 本 ， 这 个 函数 需要 你 开 尼 dynamic Groovy 
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这 些 参 数 是 否 可 用 ， 依 赖 于 你 选择 的 聚合 函数 。 
选择 view options 更 改 表 格 中 如 下 方 


e Bar Mode 当 你 为 自己 的 图 形 定义 了 多 个 Y 轴 聚 合 时 ， 你 可 以 用 这 个 选项 决定 
聚合 显示 的 方式 : 
o stacked 依次 堆 县 有 聚合 效果 。 


o percentage 每 个 聚合 显示 为 总 和 的 百分比 。 
o grouped 用 最 低 优先 级 的 子 聚合 的 结果 做 水 平分 组 。 


多 选 框 可 以 用 来 控制 以 下 行为 : 


e Show Tooltip 勾 选 该 项 显示 工具 栏 。 

e Show Legend 义 选 该 项 在 图 形 右 侧 显 示 图 例 。 

e Scale Y-Axis to Data Bounds RU by Y 轴 长 度 为 0 到 数据 集 的 最 大 值 。 勾 选 该 
项 改变 Y 轴 的 最 大 和 最 小 值 为 数据 集 的 返回 值 。 


dashboard fi& 


一 个 Kibana dashboard 能 让 你 自由 排列 一 组 已 保存 的 可 视 化 。 然 后 你 可 以 保存 这 
个 仪表 板 ， 用 来 分 享 或 者 重 载 。 


简单 的 仪表 板 像 这 样 。 





Dashboard / Example Dashboard Share Edit € @Last15minutes > 
AME. ES 
@ _ Discover Markdown Example Pie Chart Example Area Chart Example 
eo * G 
Visualize 
This is a 


Dashboard 


; tutorial 
Timelion 
e dashboard 
The markdown 
Management widget uses 
markdown syntax 
2 
Blockquotes 
in 


Count 
a 








Markdown 

0 
Use the > 10:41:00 10:43:00 10:45:00 10:47:00 10:49:00 10:51:00 — 10:53:00 
character @timestamp per 30 seconds 


Search Example 


Time ~ _source 


- 


March 30th 2017, 10:55:03.582 index: logstash-0 @timestamp: March 30th 2017, 10:55:03.582 ip: 27.72.124.209 extension: jpg response: 200 
geo.coordinates: { "lat": 33.89177944, "lon": -89.02367194} geo.src: US geo.dest: MX geo.srcdest: US:MX @tags: succ 
ess, security utc_time: March 30th 2017, 10:55:03,582 referer: http://facebook.com/success/george-nelson agent: Mozilla/5.0 (X 
11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24 clientip: 27.72.124.209 bytes: 2,895 


host: media-for-the-masses.theacademyofperformingartsandscience.org request: /uploads/zhai-zhigang.jpg url: https://media-f 
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开始 


要 用 仪表 板 ， 你 需要 至 少 有 一 个 已 保存 的 visualization » 


创建 一 个 新 的 仪表 板 


你 第 一 次 点 击 Dashboard 标签 的 时 候 ，Kibana 会 显示 一 白 的 仪表 板 


通过 添加 可 视 化 的 方式 来 构建 你 的 仪表 板 。 默 认 情 况 下 ，Kibana 仪表 板 使 用 明亮 风 
格 。 如 果 你 想 切 换 成 黑色 风格 ， 点 击 Options， 然 后 匀 选 Use dark theme ° 


自动 刷新 页 面 


你 可 以 设置 页 面 自 动 刷新 的 间隔 以 查看 最 新 索引 进来 的 数据 。 设置 会 定期 提交 
搜索 请 求 。 


529 


设置 刷新 闻 隔 后 ， 现在 菜单 栏 的 时 间 过 滤器 左 侧 。 
要 设置 刷新 间隔 : 


1. 点 击 菜单 栏 右上 角 的 Time Filter 
2. 点 击 Refresh Interval 标签 
3. 从 列表 中 选择 一 个 刷新 间隔 


要 自动 刷新 数据 ， 点 击 Auto-Refresh _ 按钮 选择 自动 刷新 闻 隔 : 


0 hits New Save Open Share CAuto-refresh € © Last15 minutes > 


Refresh Interval 


5 seconds 1 minute 1 hour 
10 seconds 5 minutes 2 hour 
30 seconds 15 minutes 12 hour 
45 seconds 30 minutes 1 day 


开局 自动 刷新 后 ，Kibana 顶部 菜单 栏 会 显示 一 个 暂停 按钮 和 自动 刷新 闻 隔 : 。 
点 击 这 个 暂停 按钮 可 以 暂停 自动 刷新 。 


添加 可 视 化 到 仪表 板 上 


要 添加 可 视 化 到 仪表 板 上 ， 点 击 工具 栏 面 板 上 的 Add。 从 列表 中 选择 一 个 已 保存 的 
可 视 化 。 你 可 以 在 Visualization Filter 里 输入 字符 串 来 过 滤 想 要 找 的 可 视 化 。 


由 你 选择 的 这 个 可 视 化 会 出 现在 你 仪表 板 上 的 一 个 容器 (container) 里 。 


保存 仪表 板 


要 保存 仪表 板 ， 点 击 工具 栏 面板 上 的 Save 按钮 ， 在 Save As 栏 输 入 仪表 板 的 名 
字 ， 然 后 点 击 Save 按钮 。 


加 载 已 保存 仪表 板 


点 击 Open 按钮 显示 已 存在 的 仪表 板 列 表 。 已 保存 仪表 板 选择 器 包括 了 一 个 文本 栏 
可 以 通过 仪表 板 的 名 字 做 过 滤 ， 还 有 一 个 链接 到 Object Editor 而 已 管理 你 的 已 保 
存 仪表 板 。 你 也 可 以 直接 点 击 Settings > Edit Saved Objects 来 访问 Object 
Editor ^ 


分 享 仪表 板 


你 可 以 分 享 仪表 板 给 其 他 用 户 。 可 以 直接 分 享 Kibana 的 仪表 板 链接 ， 也 可 以 说 入 
到 你 的 网 页 里 


用 户 必须 有 Kibana 的 访问 权限 才能 看 到 上 获 入 的 仪表 板 。 


点 击 Share 按钮 显示 HTML 代码 ， 就 可 以 徐 入 仪表 板 到 其 他 网 页 里 。 还 带 有 一 个 
指向 仪表 板 的 链接 。 点 击 复 制 按钮 “可 以 复制 代码 ， 或 者 链接 到 你 的 黏 贴 板 。 


ANLI 
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定制 仪表 板 元 素 

仪表 板 里 的 可 视 化 都 存在 可 以 调整 大 小 的 容器 里 。 接 下 来 会 讨论 一 下 容器 。 
移动 容器 

点 击 并 按 住 容器 的 顶部 ， 就 可 以 拖 动 容器 到 仪表 板 任意 位 置 。 其 他 容器 会 在 必要 的 


时 候 自动 移动 ， 给 你 在 拖 动 的 这 个 容器 空 出 位 置 。 松 开 鼠 标 ， 容 器 就 会 固定 在 当前 


停留 位 置 。 


A 
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点 击 容器 右上 角 的 X 图 标 删除 容器 。 从 仪表 板 删除 容器 ， 并 不 会 同时 删除 掉 容 器 里 
用 到 的 已 存 可 视 化 。 


查看 详细 信息 


dashboard 7 fé 


要 显示 可 视 化 背后 的 原始 数据 ， 点 击 容器 地 步 的 条 带 。 可 视 化 会 被 有 关 原 始 数据 详 
细 信 息 的 几 个 标签 蔡 换 掉 。 如 下 所 示 : 


NYCTA: Injury count by type Manhattan f x 


v 
! 


filters > Count $ 
number of cyclist injured:[1 TO *] 25 
number of motorist injured:[1 TO *] 41 
number of pedestrians injured:[1 TO *] 58 
number of persons injured:[1 TO *] 122 


Export: Raw & Formatted 去 


Page Size 10 nm 


4 


o 表格 (Table) 。 底 层 数据 的 分 页 展示 。 你 可 以 通过 点 击 每 列 顶 部 的 方式 给 该 列 数 
据 排 序 。 

e. 请 求 (Request)。 发 送 到 服务 器 的 原始 请 求 ， 以 ISON 格式 展示 。 

e 响应 (Response)。 从 服务 器 返回 的 原始 响应 ， 以 JSON 格式 展示 。 

。 统 计 值 (Statistics) 。 和 请 求 响应 相关 的 一 些 统计 值 ， 以 数据 网 格 的 方式 展示 。 
数据 报告 ， 请 求 时 间 ， 响 应 时 间 ， 返 回 的 记录 条 目 数 ， 匹 配 请 求 的 索引 模式 
(index pattern) ° 


修改 可 视 化 


点 击 容器 右上 角 的 Edit 按钮 在 Visualize 页 打开 可 视 化 编辑 。 


O1 
CD 
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timelion 介绍 


Elasticsearch 2.0 开始 提供 了 一 个 新 新 的 pipeline aggregation 特性 ， 但 是 Kibana 
iio Du a 这 方面 的 意思 ， 相 反 ，Elastic 公司 推出 了 另 一 个 实验 室 产 
: Timelion。 最 后 在 5.0 版 中 ，timelion 成 为 Kibana 5 默认 分 发 的 一 个 插件 。 


timelion 的 用 法 在 官 博 里 已 经 有 介绍 。 尤 其 是 最 近 两 篇 如 何 用 timelion 实现 异常 告 
警 的 文章 ， 更 是 从 ES 的 pipeline aggregation 细节 和 场景 一 路 讲 到 timelion 具体 

操作 ， 我 这 里 几乎 没有 再 重新 讲 一 遍 timelion 操作 入 门 i 。 不过， 官方 却 一 
直 没 有 列 出 来 timelion 支持 的 请 求 语法 的 文档 ， 而 是 在 页 面 上 通过 点 击 Docs 按钮 
的 方式 下 拉 帮 助 。 
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Kibana Timelion 







es(*).bars(), .es(mac) 1d > 


Deduplication 0% / Query Time 29ms / Processing Time 1ms o IE] 


-hide() Hide the series by default 
Jabel() Change the label of the series. Use 96s reference the existing label 
Jegend() Set the position and style of the legend on the plot 
Jines() Show the seriesList as lines 
.movingaverage() Calculate the moving average over a given window. Nice for smoothing noisey series 
.movingstd() Calculate the moving standard deviation over a given window. Uses naive two-pass algorithm. Rounding errors may become more noticeable with very long series, or series with very large numbers. 
.multiply() Multiply the values of one or more series in a seriesList to each position, in each series, of the input seriesList 
-points() Show the series as points 
.precision() number of digits to round the decimal portion of the value to 
-quandi() Pull data from quandl.com using the quand! code 
^ 
20 1.0 
m" Wilogstash 
lmac 
15 0.5 
10 0.0 


timelion 页 面 设 计 上 ， 更 接近 Kibana3 而 不 是 Kibana4 » te panel 分 布 是 通过 设 
置 几 行 几 列 的 数目 来 固化 的 ; query 框 是 唯一 的 ， 要 修改 哪个 panel 的 query > K 
标点 选 一 下 panel > query 就 自动 切换 成 这 个 panel & 1 ° 


为 了 方便 大 家 在 上 手 之 前 了 解 timelion 能 做 到 什么 ， 今 天 特意 把 timelion 的 请 求 语 
法 所 支持 的 函数 分 为 几 类 ， 罗 列 如 下 : 


可 视 化 效果 类 


e .bars($width) : 用 柱状 图 展示 数组 


e .lines($width, $fill, $show, $steps) :用 折线 图 展示 数组 

e .points() :用 散 点 图 展示 数组 

e ,color("#c6c6c6") :改变 颜色 

e .hide() :隐藏 该 数组 

e .label("change from %s") :标签 

e .legend($position, $column) :图例 位 置 

e .static(value=1024, label="1k", offset="-1d", fit="scale") :在 
图 形 上 绘制 一 个 固定 值 

e .value() : .static() 的 简写 

e .title(title="qps") : 图 表 标 题 

e .trend(mode="linear", start=0, end=-10) : A linear X log | Ja X- 

绘制 趋势 图 
e .yaxis($yaxis number, $min, $max, $position) :设置 Y 轴 属 


ME * .yaxis(2) 表示 第 二 根 Y dh 


数据 运算 类 


e .abs() : 对 整个 数组 元 素 求 绝对 值 

e .precision($number) : 浮 点 数 精度 

e .cusum($base) : 数组 元 素 之 和 ， 再 加 上 $base 

e .derivative() :对 数组 求 导 数 

e .divide($divisor) :数组 元 素 除 法 

e ,multiply($multiplier) : 数组 元 素 乘法 

e .subtract($term) : 数组 元 素 减 法 

e .sum($term) : 数组 元 素 加 法 

e .add() : 同 .sum() 

e .plus() : F .sum() 

e .first() :返回 第 一 个 元 素 

e .movingaverage($window) : 用 指定 的 窗口 大 小 计算 移动 平均 值 

e .mvavg() : .movingaverage() 的 简写 

e .movingstd($window) : 用 指定 的 窗口 大 小 计算 移动 标准 差 

e .mvstd() : HRS IO) 的 简写 

e .fit($mode) :使 用 指定 的 ff BAH A th » * 3578/4] : average, carry, 
nearest, none, scale 

e .holt(alpha=0.5, beta=0.5, gamma=0.5, season="1w", sample-2) 


FP Elasticsearch 的 pipeline aggregation 所 支持 的 holt-winters # 


e .log(base-10) : XX 

e .max() : 最 大 值 

e .min() :最 小 值 

e .props() : 附加 额外 属性 ， 比 如 .props(label-bears!) 


e .range(max-10, min-i) : 保持 形状 的 前 提 下 修改 最 大 值 最 小 值 


e .scale_interval(interval="1s") :在 新 闻 隔 下 再 次 统计 ， 比 如 把 一 个 原 


本 5min 间隔 的 date histogram 改 为 每 秒 的 结果 
e ,trim(start=1，end=-1) : 裁剪 序列 值 


逻辑 运算 类 


e .condition(operator="eq", if-100, then-200) :支持 eq、 


gt ^ Ite ^ gte 等 操作 符 ， 以 及 if、else、then 赋值 
e .if() : .condition() 的 简写 


数据 源 设 定 类 


e .elasticsearch() :从 ES 读 取 数据 


ne ^ It ^ 


e .es(q="querystring", metric="cardinality:uid", index="logstash- 


*", offset="-1d") :.elasticsearch() 的 简写 


e .graphite(metric="path.to.*.data", offset="-1d") :从 graphite 读 取 


数据 
e „quandl() :从 quandl.com 读 取 quandl 码 
e .worldbank_indicators() :从 worldbank.org 读 取 国 家 数据 
e .wbi() : .worldbank indicators() 的 简写 
e .worldbank() :从 worldbank.org 读 取 数据 
e .wb() : .worldbanck() 的 简写 
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kibana/src/core plugins/timelion/server/series functions 
现 ， 每 个 js 文件 实现 一 个 TimelionFunction 功能 。 


目录 下 实 


console 应 用 


5.0 版 本 以 后 ， 原 先 Elasticsearch 的 site plugin 都 被 废弃 掉 。 其 中 一 些 插件 作者 选 
择 了 作为 独立 的 单 页 应 用 继续 存在 ， 上 比如 前 文 介绍 的 cerebro。 而 官方 插件 ， 则 都 

迁移 成 为 了 Kibana 的 App 扩展 。 其 中 ， 原 先 归属 在 Marvel 中 的 Sense 插件 ， 被 
改名 为 Kibana console 应 用 ， 在 5.0 版 本 中 默认 随 Kibana TÈ ° 


console 应 用 的 操作 界面 和 原先 的 sense 几乎 一 模 一 样 ， 这 里 无 需 资 述 : 


Dev Tools History Settings Help 


Console 





# Delete all data in the “website” index 
DELETE /website 


# Create a document with ID 123 


PUT /website/blog/123 
"title": "My first blog entry", 
"text": "Just trying this out...", 
"date": "2014/01/01" 
“lt 
# Search! 


# Delete all data in the “website” index 
DELETE website 


# Create a document with ID 123 
PUT /website/blog/123 


"title": "My first blog entry", 


"text": “Just trying this out...", 
"date": "2014/01/01" 


要 使 用 Kibana， 你 就 得 告诉 它 你 想 要 探索 的 Elasticsearch 索引 是 那些 ， 这 就 要 配 
置 一 个 或 者 更 多 的 索引 模式 。 此 外 ， 你 还 可 以 : 


e 创建 脚本 化 字段 ， 这 个 字段 可 以 实时 从 你 的 数据 中 计算 出 来 。 你 可 以 浏览 这 种 
字段 ， 并 且 在 它 基 础 上 做 可 视 化 ， 但 是 不 能 搜索 这 种 字段 。 

e 设置 高 级 选项 ， 比 如 表格 里 显示 多 少 行 ， 常 用 字段 显示 多 少 个 。 人 和 修改 高 级 选项 
的 时 候 要 千 万 小 心 ， 因 为 一 个 设置 很 可 能 跟 另 一 个 设置 是 不 兼容 的 。 

e 为 生产 环境 配置 Kibana » 


创建 一 个 连接 到 Elasticsearch 的 索引 模式 


一 个 索引 模式 定义 了 一 个 或 者 多 个 你 打算 探索 的 Elasticsearch € 2| ° Kibana 会 查 

找 匹 配 指定 模式 的 索引 名 。 模 式 中 的 通配符 (5 匹配 堆 到 多 个 字符 。 上 比如， 模式 
myindex-* 匹配 所 有 名 字 以 myindex- 开头 的 索引 ， 比 如 myindex-1 和 
myindex-2 ° 


如 果 你 用 了 事件 时 间 来 创建 索引 名 (比如 说 ， 如 果 你 是 用 Logstash 往 Elasticsearch 
里 写 数 据 )， 索 引 模式 里 也 可 以 匹配 一 个 日 期 格式 。 在 这 种 情况 下 ， 模 式 的 静态 文本 
部 分 必须 用 中 括号 包含 起 来 ， 日 期 格式 能 用 的 字符 ， 参 见 表 1 "日 期 格式 码 " 。 


比如 ， [logstash-]YYYY.MM.DD 匹配 所 有 名 字 以 logstash- 为 前 级 ， 后 面 跟 
上 YYYY.MM.DD 格式 时 间 惟 的 索引 ， 比 如 logstash-2015.01.31 和 
logstash-2015-02-01 ° 


索引 模式 也 可 以 简单 的 设置 为 一 个 单独 的 索引 名 字 。 
要 创建 一 个 连接 到 Elasticsearch 的 索引 模式 : 


1. 切换 到 Settings > Indices 标签 页 。 
2. 指定 一 个 能 匹配 你 的 Elasticsearch 索引 名 的 索引 模式 。 默 认 的 ，Kibana 会 假 
设 你 是 要 处 理 Logstash 导入 的 数据 。 


当 你 在 顶层 标签 页 之 间 切 换 的 时 候 ，Kibana 会 记 住 你 之 前 停留 的 位 置 。 比 如 ， 
如 果 你 在 Settings 标签 页 查看 了 一 个 索引 模式 ， 然 后 切换 到 Discover 标签 ， 
再 切换 回 Settings 标签 ，Kibana 还 会 显示 上 次 你 查看 的 索引 模式 。 要 看 到 创 
建 模式 的 表单 ， 需 要 从 索引 模式 列表 里 点 击 add 按钮 。 


1. 如 果 你 索引 有 时 间 惟 字段 打算 用 来 做 基于 事件 的 对 比 ， 勾 选 Index contains 
time-based events 然后 选择 包含 了 时 间 惟 的 索引 字段 。Kibana 会 读 取 索引 
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2. 如 果 新 索引 是 周期 性 生成 ， 名 字 里 有 时 间 惟 的 ， 勾 选 Use event times to 
create index names 和 Index pattern interval 选项 。 这 会 让 Kibana 
只 搜索 哪些 包含 了 你 指定 的 时 间 范 围 内 的 数据 的 索引 。 当 你 使 用 Logstash & 
Elasticsearch 写 数 据 的 时 候 非常 有 用 。 

3. 点 击 Create 添加 索引 模式 。 

4. 要 设置 新 模式 作为 你 查看 Discover 页 是 的 默认 模式 ， 点 击 favorite 按钮 。 


表 1. 日 期 格式 码 


格式 
M 


WO 


描述 
Month - cardinal: 123... 12 
Month - ordinal: 1st 2nd 3rd ... 12th 
Month - two digit: 01 02 03 ... 12 
Month - abbreviation: Jan Feb Mar ... Dec 
Month - full: January February March ... December 
Quarter: 1234 
Day of Month - cardinal: 123... 31 
Day of Month - ordinal: 1st 2nd 3rd ... 31st 
Day of Month - two digit: 01 02 03 ... 31 
Day of Year - cardinal: 1 2 3 ... 365 
Day of Year - ordinal: 1st 2nd 3rd ... 365th 
Day of Year - three digit: 001 002 ... 364 365 
Day of Week - cardinal: 0 1 3 ... 6 
Day of Week - ordinal: Oth 1st 2nd ... 6th 
Day of Week - 2-letter abbreviation: Su Mo Tu ... Sa 
Day of Week - 3-letter abbreviation: Sun Mon Tue ... Sat 
Day of Week - full: Sunday Monday Tuesday ... Saturday 
Day of Week (locale): 0 12 ... 6 
Day of Week (ISO): 123 ... 7 
Week of Year - cardinal (locale): 1 2 3 ... 53 
Week of Year - ordinal (locale): 1st 2nd 3rd ... 53rd 


WW Week of Year - 2-digit (locale): 01 02 03 ... 53 


W Week of Year - cardinal (ISO): 123... 53 

Wo Week of Year - ordinal (ISO): 1st 2nd 3rd ... 53rd 

WW Week of Year - two-digit (ISO): 01 02 03 ... 53 

YY Year - two digit: 70 71 72 ... 30 

YYYY Year - four digit: 1970 1971 1972 ... 2030 

gg Week Year - two digit (locale): 70 71 72 ... 30 

gggg Week Year - four digit (locale): 1970 1971 1972 ... 2030 
GG Week Year - two digit (ISO): 70 71 72 ... 30 


GGGG Week Year - four digit (ISO): 1970 1971 1972 ... 2030 
A AM/PM: AM PM 


am/pm: am pm 


H Hour: 012... 23 

HH Hour - two digit: 00 01 02 ... 23 

h Hour - 12-hour clock: 1 2 3 ... 12 

hh Hour - 12-hour clock, 2 digit: 01 02 03 ... 12 
m Minute: 0 1 2 ... 59 

mm Minute - two-digit: 00 01 02 ... 59 

S Second: 0 12 ... 59 

SS Second - two-digit: 00 01 02 ... 59 

S Fractional Second - 10ths: 0 12 ... 9 

SS Fractional Second - 100ths: 0 1 ... 98 99 


SSS Fractional Seconds - 1000ths: 0 1 ... 998 999 
Timezone - zero UTC offset (hh:mm format): -07:00 -06:00 -05:00 .. 


*07:00 

Timezone - zero UTC offset (hhmm format): -0700 -0600 -0500 ... 
ZZ 

+0700 
X Unix Timestamp: 1360013296 


x Unix Millisecond Timestamp: 1360013296123 


置 上 默认 索引 模式 


默认 索引 模式 会 在 你 查看 Discover 标签 的 时 候 自 动 加 载 。Kibana 会 在 iiid > 
Indices 标签 页 的 索引 模式 列表 里 ， 给 默认 模式 左边 显示 一 个 星 号 。 你 创建 的 第 
个 模式 会 自动 被 设置 为 默认 模式 。 


要 设置 一 个 吨 外 的 模式 为 默认 索引 模式 : 


1. 进入 Settings > Indices 标签 页 。 
2. 在 索引 模式 列表 里 选择 你 打算 设置 为 默认 值 的 模式 。 
3. 点 击 模式 的 Favorite 标签 。 


你 也 可 以 在 Advanced > Settings 里 设置 默认 索引 模式 。 


重 加 载 索 引 的 字段 列表 
当 你 添加 了 一 个 索引 映射 ，Kibana 自动 扫描 匹配 模式 的 索引 以 显示 索引 字段 。 你 可 
以 重 加 载 索 引 字 段 列 表 ， 以 显示 新 添加 的 字段 。 


重 加 载 索 引 字 段 列 表 ， 也 会 重 设 Kibana 的 常用 字段 计数 器 。 这 个 计数 器 是 跟踪 你 
在 Kibana 里 常用 字段 ， 然 后 来 排序 字段 列表 的 。 


要 重 加 载 索 引 的 字段 列表 : 


1. 进入 Settings > Indices 标签 页 。 
2. 在 索引 模式 列表 里 选择 一 个 索引 模式 。 
3. 点 击 模式 的 Reload 按钮 。 


删除 一 个 索引 模式 


要 删除 一 个 索引 模式 : 


. 进入 Settings > Indices 标签 页 。 

. 在 索引 模式 列表 里 选择 你 打算 删除 的 模式 。 
点 击 模式 的 Delete 按钮 。 
.确认 你 是 想 要 删除 这 个 索引 模式 。 


上 WORD = 


创建 一 个 脚本 化 字段 


脚本 化 字段 从 你 的 Elasticsearch 索引 数据 中 即时 计算 得 来 。 在 Discover 标签 页 ， 
脚本 化 字段 数据 会 作为 文档 数据 的 一 部 分 显示 ， 而 且 你 还 可 以 在 可 视 化 里 使 用 脚本 
化 字段 。( 脚 本 化 字段 的 值 是 在 请 求 的 时 候 计 算 的 ， 所 以 它们 没有 被 索引 ， 不 能 搜索 
到 ) 

即时 计算 脚本 化 字段 非常 消耗 资源 ， 会 直接 影响 到 Kibana 的 性 能 。 而 且 记 


住 ，Elasticsearch 里 没有 内 置 对 脚本 化 字段 的 验证 功能 。 如 果 你 的 脚本 有 
bug， 你 会 在 查看 动态 生成 的 数据 时 看 到 exception 。 


脚本 化 字段 使 用 Lucene 表达 式 语法 。 更 多 细节 ， 请 阅读 Lucene Expressions 
Scripts ° 


你 可 以 在 表达 式 里 引用 任意 单个 数值 类 型 字段 ， 比 如 : 


doc['field name'].value 


要 创建 一 个 脚本 化 字段 : 


进入 Settings > Indices 

选择 你 打算 添加 脚本 化 字段 的 索引 模式 。 
. 进入 模式 的 Scripted Fields 标签 。 
点 击 Add Scripted Field ° 

. 输入 脚本 化 字段 的 名 字 。 

. 输入 用 来 即时 计算 数据 的 表达 式 。 

点 击 Save Scripted Field. 


NOOR WN > 


A X Elasticsearch 的 脚本 化 字段 的 更 多 细节 ， 阅 读 Scripting ° 


更 新 一 个 脚本 化 字段 


要 更 新 一 个 脚本 化 字段 : 


1. 进入 Settings > Indices 。 
2. 点 击 你 要 更 新 的 脚本 化 字段 的 Edit 按钮 。 
3. 完成 变更 后 点 击 Save Scripted Field 升级 。 


注意 Elasticsearch 里 没有 内 置 对 脚本 化 字段 的 验证 功能 。 如 果 你 的 脚本 有 
bug， 你 会 在 查看 动态 生成 的 数据 时 看 到 exception 。 


删除 一 个 脚本 化 字段 


要 删除 一 个 脚本 化 字段 : 


1. 进入 Settings > Indices 。 
点 击 你 要 删除 的 脚本 化 字段 的 Delete 按钮 。 


3. 确认 你 确实 想 删 除 它 。 


设置 高 级 参数 


级 参数 页 允许 你 直接 编辑 那些 控制 着 Kibana 应 用 行为 的 设置 。 比 如 ， 你 可 以 修 
AETA id ， 修 改 默认 的 索引 模式 ， 设 置 十 进 制 数值 的 显示 精度 


修改 高 级 参数 可 能 带 来 意 想不到 的 后 果 。 如 果 你 不 确定 自己 在 做 什么 ， 最 好 离 


1. 进入 Settings > Advanced 。 

点 击 你 要 修改 的 选项 的 Edit 按钮 。 
3. 给 这 个 选项 输入 一 个 新 的 值 。 

点 击 Save 按钮 。 


管理 已 保存 的 搜索 ， 可 视 化 和 仪表 板 


你 可 以 从 Settings > Objects 查看 ， 编 辑 ， 和 删除 已 保存 的 搜索 ， 可 视 化 和 仪表 
板 。 
查看 一 个 已 保存 的 对 象 会 显示 在 Discover, Visualize Dashboard 页 里 已 选择 的 
项 目 。 要 查看 一 个 已 保存 对 象 : 

1. 进入 Settings > Objects ° 

2. 选择 你 想 查 看 的 对 象 。 

3. 点 击 View 按钮 。 

编辑 一 个 已 保存 对 象 让 你 可 以 直接 修改 对 象 定义 。 你 可 以 修改 对 象 的 名 字 ， 添 加 一 
段 说 明 ， 以 及 修改 定义 这 个 对 象 的 属性 的 ISON © 


如 果 你 尝试 访问 一 个 对 象 ， 而 它 关联 的 索引 已 经 被 删除 了 ，Kibana 会 显示 这 个 对 象 
的 编辑 (Edit Object) 页 。 你 可 以 : 


e 重建 索引 这 样 就 可 以 继续 用 这 个 对 象 。 


删除 对 象 ， 然 后 用 另 一 个 索引 重建 对 象 。 


e 在 对 象 的 DST SRS EE searchSourceJSON 里 修改 引用 的 索引 


名 ， 指 向 一 个 还 存在 的 索引 模式 。 这 个 在 你 的 索引 被 重 命名 了 的 情况 下 非常 有 
用 。 


对 象 属性 没有 验证 机 制 。 提 交 一 个 无 效 的 变更 会 导致 对 象 不 可 用 。 通 常 来 说 ， 


你 还 


不 是 应 该 用 Discover, Visualize 或 Dashboard 页 面 来 创建 新 对 象 而 不 是 直接 


编辑 已 存在 的 对 象 。 


要 编辑 一 个 已 保存 的 对 象 : 


OO 人 上 omN 一 


. 进入 Settings > Objects 。 
. 选择 你 想 编辑 的 对 象 。 


点 击 Edit 按钮 。 


. 修改 对 象 定义 。 


点 击 Save Object 按钮 。 


要 删除 一 个 已 保存 的 对 象 : 


qup 


进入 Settings > Objects ° 


. Wide RAY TR o 


点 击 Delete 按钮 。 


.确认 你 确实 想 删 除 这 个 对 象 。 


Xia. kibana 服务 器 属性 


Kibana 服务 器 在 启动 的 时 候 会 从 kibana.yml 文件 读 取 属 性 设置 。 软 认 设 置 是 运 


行 在 localhost:5601 。 要 变更 主机 或 端口 ， 或 者 连接 远 端 主机 上 的 
Elasticsearch ， ree kibana.yml 文件 。 你 还 可 以 开启 SSL 或 者 设 
置 其 他 一 系列 选 


表 2. Kibana 服务 器 属性 


属性 描述 


server.port Kibana 服务 器 运行 的 端口 。 默 认 : 5601 ° 


server.host 
server.defaultRoute 
server.ssl.enabled 


server.ssl.key 


server.ssl.certificate 


pid.file 


kibana.index 


kibana.defaultAppld 


tilemap.url 


elasticsearch.url 


elasticsearch.preserveHost 


elasticsearch.requestTimeout 


elasticsearch.shardTimeout 


elasticsearch.ssl.key 


elasticsearch.ssl.certificate 


elasticsearch.tribe.url 


Kibana AR 4- R M "raj xsxbeo X: "9.0.0.0" 


3t X Kibana 时 默认 跳 转 的 地 址 。 默 认为 
/app/kibana “。 


是 否 开 局 Kibana 服务 器 的 SSL 验证 。 

Kibana 服务 器 的 密 钥 文件 路 径 。 设 置 用 来 加 密 滨 
Kibana 之 问 的 通信 。 默 认 : none » 

Kibana 服务 器 的 证 书 文件 路 径 。 设 置 用 来 加 蜜 汤 
Kibana 之 间 的 通信 。 轩 认 : none » 

你 想 用 来 存 进 程 ID 文件 的 位 置 。 如 果 没 有 指定 ， 
存在 /var/run/kibana.pid 。 

保存 搜索 ， 可 视 化 ， 仪 表 板 信息 的 索引 的 名 字 。 
认 : .kibana ° 


进入 Kibana App ERU Ë TLI T m o R 
tk: discover ° 


用 来 显示 瓦 片 地 图 的 服务 接口 URL。 想 使 用 高 德 

者 可 以 设置 

为 : "http://webrd02.is.autonavi.com/app 

lang=zh_cn&size=1&scale=1&style=7&x={x}é 

{y}&z={z}" >° 

你 想 请 求 的 索引 存在 哪个 Elasticsearch 实例 上 « 

tL: "http://localhost:9200" ° 

默认 的 ， 浏 览 器 请 求 中 的 主机 名 即 作 为 Kibana 2 

Elasticsearch 时 请 求 的 主机 名 。 如 果 你 设置 这 个 
false ,Kibana 会 改 用 elasticsearch.url 

名 。 你 应 该 不 用 担心 这 个 设置 直接 用 默认 中 

th. terie © 

等 待 Kibana 后 端 或 Elasticsearch 的 响应 的 超时 

IZS o IRIA : 30000 ° 


Elasticsearch 等 待 分 片 响应 的 超时 时 间 。 设 置 为 
闭 超时 控制 。 默 认 : 0 。 

用 来 加 密 Kibana 和 Elasticsearch 之 间 的 通信 的 
fF » BRI : none ° 

用 来 加 密 Kibana 和 Elasticsearch 之 间 的 通信 的 
件 。 默 认 : none ° 


如 果 使 用 Elasticsearch 的 Tribe Node 查询 多 个 
据 ， 需 配置 Tribe Node 的 地 址 。 
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i$ JL sub aggs 示例 

本 章 开 始 ， 就 提 到 K4/5 和 KB HRB > 4€ K4/5 中 ， 即 便 介 绍 完了 全 部 visualize 的 
配置 项 ， 也 不 代表 用 户 能 立刻 上 手 配 置 出 来 和 K3 一 样 的 面板 。 所 以 本 节 ， 会 以 几 
个 具体 的 日 志 分 析 需 求 为 例 ， 演 示 在 K4 中 ， 利 用 Elasticsearch 1.0 以 后 提供 的 
Aggregation 特性 ， 能 够 做 到 哪些 有 用 的 可 视 化 效果 。 


Ef AA T] FE FE BR 


本 书 之 前 已 经 介绍 过 logstash 如 何 利 用 multiline 或 者 log4j 4& £F AF AT B SHER © AP 
么 ， 对 函数 堆栈 ， 我 们 除了 对 底层 函数 做 基础 的 topN 排序 ， 还 能 深入 发 气 出 来 什 
么 信息 呢 ? 


下 图 是 一 个 PHP 慢 函 数 堆栈 的 可 视 化 统计 : 


[logstash-mweibo-]YYYY.MM.DD php-slow-stack-pie 





Data Options 


metrics 


D slice size Count 
buckets cous 
回 soit stices Top 10 siow.1 BEEJ slow Curl exec /data1/V5.welbo.cn/code/application/library/Comm/Http/C 22,261 
"! url.php:359 (93.35%) 
[3 spit stices Top 10 siow2 EBD request) /data1/5.welbo.cn/code/application/library/ApUPlatform.ph — 1,410 
CN. : 
N p:359 (6.33%) 
L 
© sp siices Top 10 slow.3 SESS 4 sow3 tAuth2Request( /data1/v5.welbo.cn/code/application/Iibrany/ApU/Platfo 1,111 
/ ” mvStatuses.php:77 (64.04%) 
[3 spit stices Top 10 siow.4 ESI B d slow.4 98tFriendsTimeline() /data1/v5.welbo.cn/code/application/modełs/Stat 995 
” uses.php:100 


P Add sub-buckets 


(89.5696) 





该 图 利用 了 Kibana4 的 sub aggs 特性 。 按 照 分 层次 的 函数 堆栈 ， 逐 层 做 terms 
agg。 得 到 一 个 类 似 火 焰 图 效果 的 千 层 人 饼 效果 。 
和 火焰 图 不 同 的 是 ， 千 层 饼 并 不 能 自动 深入 到 总数 堆栈 的 全 部 层次 ， 需 要 自己 手动 


指定 聚合 到 第 几 层 。 考 虑 到 重复 操作 在 页 面 上 不 是 很 方便 。 可 以 利用 Kibana4 的 
url 特性， 直接 修改 地 址 生成 效果 。 上 图 的 Url 如 下 : 


http: //k4domain: 5601/#/visualize/edit/php-slow-stack-pie?_g=()&_ 
a=(filters:!(),linked:!t, query: (query_string: (query:'*')),vis:(a 
ggs:!((id:'1',params:(),schema:metric, type:count), (id:'2', params 
:(field:slow.1, order:desc, orderBy: '1',size:10),schema:segment, ty 
pe:terms),(id:'3', params: (field:slow.2,order:desc,orderBy: '1',Si 
ze:10),schema:segment, type:terms), (id:'4', params: (field:slow.3,0 
rder:desc,orderBy: '1',size:10),schema:segment, type: terms), (id: '5 
', params: (field:slow.4,order:desc, orderBy: '1',size:10),schema:se 
gment, type: terms) ), listeners: (),params: (addLegend:!f,addTooltip: 
It, defaultYExtents:!f,isDonut:!t,shareYAxis:!t,spyPerPage:10), ty 


pe:pie)) 


可 以 看 到 ， 如 果 打 算 增 减 堆栈 的 聚合 层次 ， 对 应 增 减 一 段 (id:'5',params: 
(field:slow.4,order:desc,orderBy:'1',size:10), 就 可 以 了 。 


作为 国定 可 视 化 分 析 模式 的 另 一 种 分 享 办 法 ， 还 可 以 导出 该 visualize object 在 
.kibana 索引 中 的 JSON 记录 。 这 样 其 他 人 只 需要 原样 再 导入 到 自己 的 
.kibana 索引 即 可 : 


# curl 127.0.0.1:9200/.kibana/visualization/php-slow-stack-pie/_ 
source 

{"title": "php-slow-stack-pie", 'visState":"(N'aggsN" : [(N" idN" :N"1 
X", N'paramsN" : £3, N schema N" :N"metricN", \"type\":\"count\"}, (N" id 
NENT \"params\":{\"field\":\"slow.1\",\"order\":\"desc\",\"o 
rderBy\":\"1\",\"size\":10}, \"schema\":\"segment\", \"type\":\"te 
rms\"}, {\"id\":\"3\",\"params\":{\"field\":\"slow.2\",\"order\": 
\"desc\", N'orderByN" :N"1N" , A"sizeN" :10), NV'schemaN" :N'segmentN" , N 
"type\":\"terms\"}, (N' idN" :N" AN", N"paramsN" : (N" feldN" :N" slow. 3N 
" \"order\":\"desc\", \"orderBy\":\"1\",\"size\":10},\"schema\":\ 
"segment\", \"typeN\":\"terms\"}, {\"id\":\"5\",\"params\": (N" field 
NU" :NU"slow.4N" , N'orderN" : N desc N", \"orderBy\":\"1\", \"size\":10}, 
X"schemaN" : N" segment N" , \"type\":\"terms\"}],\"listeners\":{},\"p 
arams\": {\"addLegend\": false, \"addTooltip\": true, \"defaultYExten 
ts\": false, \"isDonut\": true, N'shareYAxisN" : true, \"spyPerPage\":1 
0), \"type\":\"pie\"}", "description":"","savedSearchId" : "php-fpm- 
slowlog", version":1,"kibanaSavedObjectMeta":("searchSourceJSON" 
:"{\"filter\":[]}"}} 


上 面 记录 中 可 以 看 到 ， 这 个 visualize 还 关联 了 一 个 savedSearch > 7f Z ME » A 
从 .kibana 索引 里 把 这 个 内 容 也 导出 : 


# curl 127.0.0.1:9200/.kibana/search/php-fpm-slowlog/ source 
{"title":"php-fpm-slowlog","description":"","hits":0, "columns": [ 
" Ssource"], "sort":["Qtimestamp", "desc"], "version":1, "kibanaSaved 
ObjectMeta": {"searchSourceJSON":"{\n \"index\": \"[logstash-mwe 
ibo-]YYYY.MM.DDN", Nn  \"highlight\": (^n \"pre_tags\": [Nn 
\"@kibana-highlighted-field@\"\n ],\n \"post_tags\": [\ 


n \"@/kibana-highlighted-field@\"\n ],\n \"fields\": 
{\n Ne ee RNN }\n },\n \"filter\": PAD {\n x 
"meta\": {\n \"index\": \"[logstash-mweibo-]YYYY.MM.DD\", 
\n \"negate\": false, \n \"key\": \"_type\", Nn 
\"value\": \"php-fpm-slow\", \n \"disabled\": false\n 
},\n \"query\": {\n \"match\": {\n AVT 
ype\": (^n \"query\": \"php-fpm-slow\", \n 
\"type\": \"phrase\"\n jn jn jn jn 
],\n \"query\": (Nn \"query_string\": [^n \"query\": \" 
ENN \"analyze_wildcard\": true\n JAn }\n}"}} 


这 个 内 容 看 起 来 有 点 怪 怪 的 ， 其 实 把 searchsourceJSON 字符 串 复 制 出 来 ， 在 终 
端 下 贴 到 echo -ne 命令 后 面 ， 回 车 即 可 看 到 其 实 是 这 样 : 


"index": "[logstash-mweibo-]YYYY.MM.DD", 
"highlight": { 
"pre tags": [ 
"Qkibana-highlighted-fieldQ" 
] 
"post_tags": T 
"Q/kibana-highlighted-fieldQ" 
] 
"fields": ( 
iem 
} 
ty 
"filter": [ 
t 
"meta": { 
"index": "[logstash-mweibo-]YYYY.MM.DD", 
"negate": false, 
"key": " type", 
"value": "php-fpm-slow", 
"disabled": false 
ty 
"query": { 
"match": { 
"_type": { 
"query": "php-fpm-slow", 
"type": "phrase" 


} 
], 
"query": ( 
"query string": { 
OIG Tyrie eee Rte 
"analyze_wildcard": true 
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分 图 统计 


上 一 节 我 们 展示 了 sub aggs 在 饼 图 上 的 效果 。 不 过 这 多 层 agg， 其 实用 的 是 同一 
类 数据 。 如 果 在 聚合 中 ， 要 加 上 一 些 完 全 不 同 纬度 的 数据 ， 还 是 在 单一 的 图 片上 继 
续 累 加 就 不 是 很 直观 了 。 比 如 说 ， 还 是 上 一 节 用 到 的 PHP E RER o RTA 
根据 机 房 做 一 下 拆 分 。 由 于 代码 部 署 等 主动 变更 都 是 有 灰 度 部 署 的 ， 一 旦 发 现 某 机 
房 有 异常 ， 就 可 以 及 时 处 理 了 。 


同样 还 是 新 建 sub aggs， 但 是 在 开始 ， 选 择 split chart 而 不 是 split slice ° 
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从 URL 里 可 以 看 到 ， 分 图 的 aggs 是 schema:split ， 而 饼 图 分 片 的 aggs = 


schema:segment 


O1 
C1 


http: //k4domain: 5601/#/visualize/edit/php-slow-stack-pie?_g=(ref 
reshinterval: (display: Off, pause: !f,Ssection:0,value:0), time: (from 
: now- 12h, mode: quick, to:now) )&_a=(filters:!(),linked:!t, query: (qu 
ery_string: (query: '*')),vis:(aggs:!((id:'1',params:(),schema:met 
ric, type:count), (id: '6', params: (field:idc, order:desc, orderBy: '1' 
,row:!f,size:5),schema:split, type:terms),(id:'2',params:(field:s 
low.1,order:desc,orderBy:'1',size:10), schema: segment, type: terms) 
,(id:'3', params: (field:slow.2,order:desc, orderBy: '1',size:10),sc 
hema:segment, type: terms), (id:'4', params: (field:slow.3, order:desc 
,OrderBy:'1',size:10), schema:segment, type:terms), (id:'5',params: 
(field:slow.4,o0rder:desc,orderBy:'1',size:10), schema: segment, typ 
e:terms)),listeners:(),params:(addLegend: ! f,  addTooltip:!t,defaul 
tYExtents:!f,isDonut:!t,shareYAxis:!t,spyPerPage:10), type: pie)) 


TopN £4 5 5-38 35 A 


TopN 的 时 序 趋势 图 是 将 Elastic Stack 用 于 监控 场景 最 常用 的 手段 。 乃 至 在 
Kibana3 时 代 ， 开 发 者 都 通过 在 Query 框 上 额外 定义 TopN 输入 的 方式 提供 了 这 个 
特性 。 不 过 在 Kibana4 中 ， 因 为 sub aggs 的 依次 分 桶 原理 ，TopN 时 序 趋 势 图 又 
有 了 新 的 特点 。 


Kibana3 中 ， 请 求实 质 是 先 单独 发 起 一 次 termFacet 请 求 得 到 topN， 然 后 再 发 起 带 
有 facetFilter 的 dateHistogramFacet ， 分 别 请 求 每 个 term 的 时 序 。 那 么 同样 的 原 
理 ， 迁 移 到 Kibana4 中 ， 就 是 先 利 用 一 次 termAgg 分 桶 后 ， 再 每 个 桶 内 做 
dateHistogramAgg 了 。 对 应 的 Kibana4 地 址 为 : 


http://k4domain:5601/#/visualize/edit/php-fpm-slowlog-histogram? 
_g=(refreshInterval:(display:0ff, pause:!f,section:0,value:0),tim 
e:(from:now-12h, mode: quick, to:now) )&_a=(filters:!(),linked:!t,qu 
ery: (query_string:(query:'*')),vis:(aggs:!((id:'1',params:(),sch 
ema:metric, type:count),(id:'3',params:(field:host, order:desc,ord 
erBy:'1',size:3),schema: group, type:terms), (id: '2', params: (custom 
Interval: '2h',extended_bounds:(), field: '@timestamp',interval:aut 
o,min doc count:1),schema:segment,type:date histogram)),listener 
s:(),params:(addLegend:!t,addTimeMarker:!f,addTooltip:!t,default 
YExtents:!t,interpolate:linear,mode:stacked,scale:linear,setYExt 
ents:!f,shareYAxis:!t,smoothLines:!f,times:!(),yAxis:()),type:ar 
ea)) 


效果 如 下 : 
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% This visualization is linked to a saved search: php-fpm-slowlog 


Axis. Count 


+ Add metrics 


tric: Count 
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可 以 看 到 图 上 就 是 3 RA? PARR top3 的 host 的 时 序 。 


一 般 来 说 ， 这 样 都 是 够 用 的 。 不 过 如 果 经 常 有 host 变动 的 时 候 ， 在 这 么 大 的 一 个 
时 间 范 围 内 ， 求 一 次 总 的 topN， 可 能 就 海 没 了 一 些 肯 间 的 变动 了 。 所 以 ， 在 


Ki 


bana4 上 ， 我 们 可 以 把 sub aggs 的 顺序 颠倒 一 下 。 先 按 dateHistogramAgg 分 


桶 ， 再 在 每 个 时 间 桶 内 ， 做 termAgg。 对 应 的 Kibana4 地 址 为 : 


可 


http: //k4domain: 5601/#/visualize/edit/php -fpm-slowlog-histogram? 
_g=(refreshInterval: (display: Off, pause:!f,section:0,value:0), tim 
e:(from:now-12h, mode: quick, to:now) )&_a=(filters:!(),linked:!t,qu 
ery: (query_string: (query:'*')),vis:(aggs:!((id:'1',params:(),sch 
ema:metric, type:count),(id:'2', params: (customInterval: '2h',exten 
ded bounds:(),field:'Qtimestamp',interval:auto,min doc count:1), 
schema:segment,type:date histogram),(id:'3',params:(field:host,o 
rder:desc,orderBy:'1',size:3), schema:group, type:terms)), listener 
s:(),params:(addLegend:!t,addTimeMarker:'!f,addTooltip:'!t,default 
YExtents:!t,interpolate:linear,mode:stacked, scale:linear,setYExt 
ents:!f,shareYAxis:!t,smoothLines:!f,times:!(),yAxis:()),type:ar 
ea)) 


以 对 比 一 下 前 一 条 url， 其 中 就 是 把 id 为 2 和 3 的 两 段 做 了 对 调 。 而 最 终 效 果 如 


F: 





% This visualization is linked to a saved search: php-fpm-slowlog 
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响应 时 间 的 百 分 占 比 趋势 图 


时 序 图 M 上 节 展 示 的 最 基本 的 计数 以 外 ， 还 可 以 在 站 轴 上 使 用 其 他 数值 统计 结 
果 。 最 常见 的 ， 比 如 访问 日 志 的 平均 响应 时 间 。 但 是 平均 值 在 数学 统计 中 ， 是 一 个 
非常 不 可 信 的 数据 。 稍 微 几 个 远离 置信 区 间 的 数值 就 可 以 严重 影响 到 平均 值 。 所 
以 ， 在 评价 数值 的 总 体 分 布 情况 时 ， 更 推荐 采用 四 分 位 数 。 也 就 是 25%，50%， 
75%。 在 可 视 化 方面 ， 一般 采 用 箱 体 图 方式 。 


Kibana4 没有 箱 体 图 的 可 视 化 方式 。 不 过 采用 线 图 ， 我 们 一 样 可 以 做 到 类 似 的 效 
果 o 


ped 时 序数 据 基础 上 ， 改 变 Y 轴 数 据 源 ， 选 择 Percentile 方式 ， 然 后 输入 具 
Z BP] o 


体 的 四 分 位 。 运 行 演 





对 比 新 的 URL， 可 以 发 现 变化 的 就 是 id 为 1 的 片段 。 变 成 了 (id:'1', params: 
(field:connect ms,percents:! 


(50,75,95,99)), schema:metric,type:percentiles) 


http: //k4domain: 5601/#/visualize/create?type=area&savedSearchId= 
curldebug& g-()& a-(filters:!(),linked:!t,query:(query string:(q 
uery:'*')),vis:(aggs:!((id:'i1',params:(field:connect ms,percents 
:1(50,75,95,99)), schema:metric,type:percentiles),(id:'2',params: 
(customInterval:'2h',extended bounds:(),field:'Qtimestamp',inter 
val:auto,min doc count:1),schema:segment,type:date histogram)),1l 
isteners:(),params:(addLegend: !f, addTimeMarker:!f,addTooltip: !t, 
defaultYExtents:!f,interpolate:linear,mode:stacked,scale:linear, 
setYExtents:!f,shareYAxis:!t,smoothLines:!t,times:!(),yAxis:()), 
type:area)) 


实践 表明 ， 在 访问 日 志 数据 上 ， 平 均 数 一 般 相近 于 75% 的 四 分 位 数 。 所 以 ， 为 了 
更 细 化 性 能 情况 ， 我 们 可 以 改 用 诸如 90%，95% 这 样 的 百 分 位 。 


此 外 ， 从 Kibana4.1 开始 ， 新 加 入 了 Percentile rank 有 聚合 支持 。 可 以 在 丫 轴 数 据 
源 里 选择 这 种 聚合 ， 输 入 有 具体 的 响应 时 间 ， 比 如 2s。 则 可 视 化 数据 变 成 2s 内 完成 
的 响应 数 占 总 数 的 百分比 的 趋势 图 。 


响应 时 间 的 概率 分 布 在 不 同时 段 的 相似 度 对 比 


前 面 已 经 用 百 分 位 的 时 序 ， 展 示 如 何 更 准确 的 监控 a el o 那么， 还 能 不 
能 更 进一步 呢 ? 在 制定 SLA 的 时 候 ， nner ns 么 才能 确定 当前 服务 
的 拐点 ?了 除了 压 测 以 外 ， oy d E 一 下 概率 分 布 。 
Kibana4 对 此 提供 了 直接 的 支持 ， 我 们 可 以 以 数值 而 非 时 间作 为 X 轴 数 据 。 


那么 进一步 ， 我 们 怎么 区 分 不 同 产品 在 同一 时 间 ， 或 者 相同 产品 在 不 同时 间 ， 性 能 
上 有 无 渐变 到 质变 的 可 能 ?3 这里， 我 们 可 以 采用 grouped 方式 ， 来 排列 filter 
aggs 的 结果 : 


urlpath:*/2/users/show"* AND request_time:<1 


lus 
R9$8888988883228228939228892928222828322288229283222828328 





AXI] 9D AE BUR 0 RR A AIRE AR AMA LAA > ee REN 
升 ， 没 有 明显 的 异 变 。 


当然 ， 如 果 觉 得 目测 不 靠 谱 的 ， 可 以 把 两 组 数值 拿 下 来 ， 通 过 PDL ` scipy ` 
matlab ^ R 等 工具 做 具体 的 差异 显著 性 检测 。 这 就 属于 后 续 的 二 次 开发 了 。 


filter 中 ， 可 以 写 任意 的 query string 语法 。 不 限于 本 例 中 的 时 间 段 : 


http: //k4domain: 5601/#/visualize/create?type=histogram&indexPatt 
ern=%5Blogstash-mweibo-nginx-%5DYYYY .MM.DD&_g=()&_a=(filters:!() 
, linked: !f, query: (query_string: (analyze wildcard: !t,query: 'reque 
st_time:%3C50')),vis:(aggs:!((id:'1',params:(),Sschema:metric, typ 
e:count), (id: '3', params: (filters: !((input: (query: (query_string: ( 
analyze wildcard:!t,query:'Qtimestamp:965B9622now - 7M%22%20T0%20%22 
now%22%5D')))), (input: (query: (query_string: (analyze wildcard:!t, 
query: '@timestamp : %5B%22now- 15m%22%20T0%20%22now- 7m%22%7D')))))) 
, schema: group, type:filters), (id: '2', params: (extended_bounds:(),f 
ield:request_time, interval:1),schema:segment, type:histogram)),1i 
steners:(),params: (addLegend: !t, addTimeMarker:!f,addTooltip:!t,d 
efaultYExtents: !f,mode:grouped, scale: linear,setYExtents:!f,share 
YAxis:!t,spyPerPage:10,times:!(),yAxis:()),type:histogram)) 


源码 剖析 


Kibana 4 开始 采用 angular.js + node.js 框架 其 中 node.js 主要 提供 两 部 分 功 
能 ， 给 Elasticsearch 做 搜索 请 求 转发 代理 ， 以 及 auth、ssl、setting 等 操作 的 服务 
器 后 端 ? 5.0 版 本 在 这 些 基础 构成 方面 没有 太 大 变化 。 


本 章节 假设 你 已 经 对 angular 有 一 定 程度 了 解 。 所 以 不 会 再 解释 其 中 angular 的 
route > controller > directive > service > factory 等 概念 。 


to X 4T Hit 4% kibana 3 的 CAS 验证 功能 到 Kibana 4 或 5 版 本 ， 那 么 可 以 稍微 了 
解 一 下 Hapi.JS 框架 的 认证 扩展 ， 相 信 可 以 很 快 修改 成 功 。 


本 章 主 要 还 是 集中 在 前 端 kibana 页 面 功能 的 实现 上 。 


参考 阅读 


e 在 ElasticfON} 大 会 上 ， 也 有 专门 针对 Kibana 4 源码 和 二 次 开发 入 门 的 演讲 。 
请 参阅 : https://speakerdeck.com/elastic/the-contributors-guide-to-the- 
kibana-galaxy 

e 专业 的 前 端 工程 师 怎么 看 Kibana 4 的 代码 
的 : http://www.debuggerstepthrough.com/2015/04/reviewing-kibana-4s- 
client-side-code.html ° 

e 如 何 通 过 Hapi 的 Proxy 功能 实现 认证 : kbn-authentication-plugin 


kibana_index 结构 


包括 有 以 下 type : 


config 


_id 为 kibana5 的 version。 内 容 主要 是 defaultIndex > 3X Æ RU &4 index pattern. 


search 


id 为 discover 上 保存 的 搜索 名 称 。 内 容 主要 是 title * column * sort > version * 
description > hits 和 kibanaSavedObjectMeta ° kibanaSavedObjectMeta 内 是 一 个 
searchSourceJSON : 保存 搜 索 json 的 字符 串 。 


visualization 


_id A visualize 上 保存 的 可 视 化 名 称 。 内 容 包括 tile，savedSearchld > 

description > version * kibanaSavedObjectMeta 和 visState，uiStateJSON“。 其 中 
visState 里 保存 了 RS json FB o dec JE T CURES RUE > MALE 
search 类 型 里 的 _id 存在 savedSearchld 字段 里 ， 如 果 是 从 新 搜索 开始 的 ， 那 么 把 
搜索 json 的 字符 串 直接 存在 自己 的 kibanaSavedObjectMeta 的 
searchSourceJSON 里 。 


dashboard 


_id A dashboard 上 保存 的 仪表 盘 名 称 。 内 容 包括 title, version > timeFrom ， 
timeTo » timeRestore > uiStateJSON ° optionsJSON ° hits > refreshlnterval > 
panelsJSON 和 kibanaSavedObjectMeta » X ? panelsJSON 是 一 个 数组 ， 每 个 元 
素 是 一 个 panel 的 属性 定义 。 定 义 包 括 有 : 


e type: 具体 加 载 的 app 类 型 ， 就 默认 来 说 ， 肯 定 就 是 search 或 者 visualization 
之 一 。 
e id: 具体 加 载 的 app 的 保存 id。 也 就 是 上 面 说 过 的 ， 它 们 在 各 自 类 型 下 的 


id 内 容 。 
e size x: panel 的 X 轴 长 度 。Kibana 采用 gridster 库 做 挂件 的 动态 划分 ， 默 认 
为 3。 
e Size y: panel 的 Y 轴 长 度 。 黑 认为 2。 
e col: panel 的 左边 侧 起 始 位 置 。Kibana 指定 col 最 大 为 12。 每 行 第 一 个 panel 
的 col 就 是 1， 假如 它 的 size x X 4 * ABA H—* panel 的 col 就 是 5。 
e row: panel 位 于 第 几 行 。gridster 默认 的 row 最 大 为 15。 


index-pattern 


_id A setting 中 设置 的 index pattern。 内 容 主要 是 匹配 该 模式 的 所 有 索引 的 全 部 字 
段 与 字段 映射 。 如 果 是 基于 时 间 的 索引 模式 ， 还 会 有 主 时 间 字 段 timeFieldName 和 
时 间 间 隔 intervalName 两 个 字段 。 


field 数组 中 ， 每 个 元 素 是 一 个 字段 的 情况 ， 包 括 字 段 的 type, name, indexed, 
analyzed, doc values, count, scripted，searchable，aggregationable，format > 
popularity 这 些 状态 。 


如 果 scripted A true， 那 么 这 个 元 素 就 是 通过 kibana 页 面 添 加 的 脚本 化 字段 ， 那 


么 这 条 字段 记录 还 会 额外 多 几 个 内 容 : 


e script: 记录 实际 script 7% 4) ° 

e lang: 在 Elasticsearch 的 datanode 上 采用 什么 lang-plugin 运行 。 默 认 是 
painless » FP Elasticsearch 5 开始 默认 启用 的 脚本 引擎 。 可 以 在 management 
页 面 上 切换 成 Lucene expression 等 其 他 你 的 集群 中 可 用 的 脚本 语言 。 


timelion sheet 


包括 有 timelion chart height > timelion columns ° timelion interval > 
timelion other. interval > timelion rows ° timelion sheet 等 字段 


小 贴 士 


在 本 书 之 前 介绍 packetbeat 时 提 到 的 自 带 dashboard 导入 脚本 ， 其 实 就 是 通过 
curl 命令 上 传 这 些 JSON 到 kibana index 索引 里 。 


.kibana 索 引 的 数据 结构 
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我 们 先 从 启动 Kibana 的 命令 行程 序 入 手 ， 可 以 看 到 这 是 一 个 shell 脚本 。 最 终 执行 
的 是 node src/cli serve 命令 。 然 后 跟着 就 可 以 找到 src/cli/serve # 

序 ， 其 中 最 重要 的 是 加 载 了 src/server/kbn server.js 。 继 续 打 开 ， 可 以 看 到 
它 先后 加 载 了 config, http, logging, plugin 和 uiExports。 毫 无 疑问 ， 其 中 重点 是 
http 和 uiExports 部 分 。 


http/index.js 中 ， 和 初始 化 了 Hapi.Server *1 €. > 7» 3 hapi plugin， 并 声明 了 主 
要 的 route。 包 括 静 态 文 件 、 模 板 文件 、 短 地 址 跳 转 和 主页 默认 跳 转 到 

/app/kibana 。 目 前 来 说 Kibana 在 服务 器 端 主动 做 的 事情 还 比较 少 。 在 我 们 不 
基于 Hapi 框架 做 二 次 开发 的 情况 下 ， 不 用 过 于 关注 这 期 间 Kibana 做 了 什么 。 


下 面 进 入 src/ui/ 目录 继续 。 


src/ui/index.js 中 完成 了 更 细节 的 各 类 app 的 加 载 和 路 由 分 配 : 


const uiExports = kbnServer.uiExports = new UiExports({ 
urlBasePath: config.get('server.basePath') 

3); 

for (let plugin of kbnServer.plugins) { 
uiExports.consumePlugin(plugin); 


const bundles - kbnServer.bundles - new UiBundleCollection(bundl 
erEnv, config.get('optimize.bundleFilter')); 


for (let app of uiExports.getAllApps()) { 
bundles.addApp(app); 
} 
server.route({ 
path: '/app/{id}', 
method: 'GET', 
handler: function (req, reply) { 
const id = req.params.id; 
const app = uiExports.apps.byId[id]; 
if (!app) return reply(Boom.notFound('Unknown app ' + id)); 


if (kbnServer.status.isGreen()) { 
return reply.renderApp(app); 

} else { 
return reply.renderStatusPage(); 


3); 


可 以 看 到 这 里 把 所 有 的 app 都 打包 进 了 bundle。 这 也 是 很 多 初次 接触 Kibana 二 次 
开发 的 新 手 很 容易 被 绊 倒 的 一 点 改 了 一 行 代码 怎么 没 生 效 ? 因为 服务 是 优先 使 
用 bundle 内 容 的 ， 而 不 会 每 次 都 进 到 各 源码 目录 执行 。 





如 果 确 实在 频繁 修改 代码 的 阶段 ， 每 次 都 等 bundle 确实 太 系 了 ， 可 以 看 到 上 面 代 
码 段 里 有 一 个 config.get('optimize.bundleFilter') 。 是 的 ， 其 实 Kibana 
支持 在 config 中 设 定 具 体 的 optimize 行为 ， 但 是 官方 文档 上 并 没有 介绍 。 最 完整 
的 配置 项 ， 见 src/server/config/schema.js 。 前 文 说 过 ， 这 是 在 启动 

kbn server 的 时 候 最 先 加 载 的 。 


在 schema 中 可 以 看 到 一 个 很 可 爱 的 配置 


optimize: _joi2['default'].object({ 
enabled:  joi2['default'].boolean()['default'](true), 
}) 


所 以 你 只 要 在 config/kibana.yml 中 加 上 这 么 一 行 配置 就 好 


J : optimize.enabled: false 。 


kibana app 


从 Kibana 4.5 版 开始 ，Kibana 框架 和 Kibana App 做 了 一 个 剥离 。 现 在 ， 我 们 进 
到 Kibana App 里 看 看 。 路 径 在 src/core plugins/kibana 。 


我 们 可 以 看 到 路 径 中 有 如 下 文件 : 


e common/ 

e index.js 

e package.json 
e public/ 

e server/ 


这 是 一 个 很 显然 的 普通 nodejs 模块 的 结构 。 我 们 可 以 看 看 作为 模块 描述 的 
package.json 里 写 了 啥 : 


{ 
"name": "kibana", 
"version": "kibana" 


非常 有 趣 的 version。 事 实 上 这 个 写法 的 意思 是 本 插件 的 版 本 号 和 Kibana 框架 的 版 
本 号 保持 一 致 。 事 实 上 所 有 core plugins 的 版 本 号 都 写 的 是 kibana 。 

然后 index.js 中 ， 调 用 UiExports 完成 了 app 注册 。 也 这 是 之 后 我 们 自己 开发 新 的 
Kibana 应 用 时 必须 做 的 。 我 们 下 面 摘 主 要 段落 分 别 看 一 下 : 


module.exports = function (kibana) { 
var kbnBaseUrl = '/app/kibana'; 
return new kibana.Plugin({ 
id: 'kibana', 
config: function config(Joi) { 
return Joi.object({ 
enabled: Joi.boolean()['default'](true), 
defaultAppId: Joi.string()['default']('discover'), 
index: Joi.string()['default']('.kibana') 
3)['default'](); 
ty 
uiExports: { 
app: { 
id: 'kibana', 
title: 'Kibana', 
listed: false, 
description: 'the kibana you know and love', 
main: 'plugins/kibana/kibana', 


这 是 最 基础 的 部 分 ， 注 册 成 为 一 个 kibana.Plugin > id “4A > config 配置 有 什 
么 ， 标 题 叫 什么 ， 入 口 文件 是 哪个 ， 具 体 是 什么 类 型 的 uiExports， 一 般 常见 的 选 
择 有 : app、visType。 这 两 者 也 是 做 Kibana 二 次 开发 最 容易 入 手 的 地 方 。 


uses: ['visTypes', 'spyModes', 'fieldFormats', 'navbarE 
xtensions', 'managementSections', 'devTools', 'docViews'], 
injectVars: function injectVars(server, options) {...} 


uses 和 injectVars 是 可 选 的 方式 ， 可 以 在 src/ui/ui app.js 中 看 到 起 作用 。 
分 别 是 指明 下 列 模块 已 经 加 载 过 ， 以 后 就 不 用 再 加 载 了 ; 以 及 声明 需要 注入 浏览 器 
的 JSON 变量 。 


links: [( 
id: 'kibana:discover', 
title: 'Discover', 
order: -1003, 
url: kbnBaseUrl + '#/discover', 
description: 'interactively explore your data', 
icon: 'plugins/kibana/assets/discover.svg' 


这 里 是 一 个 特殊 的 地 方 ， 一 般 来 说 其 他 应 用 不 会 用 到 links 类 型 的 uiExports » AA 
Kibana 应 用 本 身 不 用 单一 的 左 侧 边栏 切换 ， 而 是 需要 把 自己 内 部 的 Discover、 
Visualize、Dashboard、Management 功能 放 上 去 。 所 以 定义 里 ， 把 自己 的 
listed 给 false 了 ， 而 把 这 具体 的 四 项 通过 links 的 方式 ， 添 加 到 侧 边 栏 上 。 
links 具体 可 配置 的 属性 ， 见 src/ui/ui nav link.js 。 这 里 就 不 细 讲 了 。 


preInit: _asyncToGenerator(function* (server) { 
yield mkdirp(server.config().get('path.data')); 


3), 


prelnit 也 是 一 个 可 选 属 性 ， 如 果 有 需要 创建 目录 之 类 的 要 预先 准备 的 操作 ， 可 以 在 


init: function init(server, options) { 
// uuid 
(0, _serverLibManage_uuid2['default'])(server); 
// routes 
(0, _serverRoutesApilIngest2['default'])(server); 
(0, _serverRoutesApiSearch2['default'])(server); 
(0, _serverRoutesApiSettings2['default'])(server); 
(0, _serverRoutesApiScripts2['default'])(server); 


server .expose('systemApi', systemApi); 


T): 


init 是 最 后 一 步 。 我 们 看 到 Kibana 应 用 的 最 后 一 步 是 继续 加 载 了 一 些 服 务 器 端的 
route 设置 。 比 如 这 个 _serverRoutesApiScripts2 ， 具 体 代 码 是 在 
src/core_plugins/kibana/server/routes/api/scripts/register_language 
smsi EX: 


server.route({ 
path: '/api/kibana/scripts/languages', 
method: 'GET', 
handler: function handler(request, reply) { 
var callWithRequest = server.plugins.elasticsearch.callWithR 
equest; 
return callWithRequest(request, 'cluster.getSettings', { 
include defaults: true, 
filter path: '**.script.engine.*.inline' 
}).then(function (esResponse) { 
var langs = _lodash2['default'].get(esResponse, ‘defaults. 


script.engine', {}); 


var inlineLangs = _lodash2['default'].pick(langs, function 
(lang) { 
return lang.inline === 'true'; 
3); 
var supportedLangs =  lodash2['default'].omit(inlineLangs, 


'mustache'); 
return lodash2['default'].keys(supportedLangs); 


}).then(reply)['catch'](function (error) { 
reply((0,  libHandle es error2['default'])(error)); 


3); 


我 在 之 前 KA 源码 解析 中 曾经 讲 过 的 一 个 二 次 开发 场景 一 ”切换 脚本 引擎 支持 。 在 
Elasticsearch 5.0 中 ， 在 / cluster/settings 接口 里 提供 了 具体 的 可 用 引擎 细 
节 ， 诸 如 一 个 个 script.engine.painless.inline 的 列表 。 这 样 ， 就 不 必 像 之 
前 那样 明确 知道 自己 可 以 用 什么 ， 然 后 硬 改 代码 来 支持 了 ; 而 是 可 以 通过 这 个 接口 
数据 ， 拿 到 集群 实际 支持 什么 引擎 ， 当 前 默认 是 什么 引擎 等 设置 ， 直 接 在 Kibana 
中 使 用 。 上 面 这 段 代 码 ， 就 是 提供 了 这 个 数据 。 


注意 其 中 排除 了 mustache， 因 为 它 只 能 做 模板 演 染 ， 没 法 做 字段 值 计 算 。 


WN 


好 了 。 应 用 注册 完成 ， 我 们 看 到 了 main 入 口 ， 那 么 去 看 看 main A^ CHARS 
打开 src/core plugins/kibana/public/kibana.js 。 主 要 如 下 


import kibanaLogoUrl from 'ui/images/kibana.svg'; 
import 'ui/autoload/all'; 

import 'plugins/kibana/discover/index'; 
import 'plugins/kibana/visualize/index'; 
import 'plugins/kibana/dashboard/index'; 
import 'plugins/kibana/management/index'; 
import 'plugins/kibana/doc'; 

import 'plugins/kibana/dev tools'; 

import 'ui/vislib'; 

import 'ui/agg response'; 

import 'ui/agg types'; 

import 'ui/timepicker'; 

import Notifier from 'ui/notify/notifier'; 
import 'leaflet'; 


routes.enable(); 


routes 
.otherwise({ 
redirectTo: ^/$(chrome.getInjected('kbnDefaultAppId', 'discove 
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chrome 
.setRootController('kibana', function ($scope, courier, config) 


{ 


$scope.$on('application.load', function () { 
courier.start(); 


+); 


3): 


基本 上 通过 这 一 串 import 就 可 以 看 到 Kibana 中 最 主要 的 各 项 功能 了 。 


而 对 内 部 比较 重要 的 则 是 这 个 ui/autoload/all 。 这 里 面 其 实 是 加 载 了 kibana 
自 定 义 的 各 种 angular module ` directive 和 filter。 像 我 们 熟悉 的 markdown ^ 

moment、auto_select、json_input、paginate、file_upload 等 都 在 这 里 面 加载 。 这 

些 都 是 网 页 开发 的 通用 工具 ， 这 里 就 不 再 介绍 细节 了 ， 有 兴趣 的 读者 可 以 在 
src/ui/public/ 下 找到 对 应 文件 。 


设置 routes 的 具体 操作 在 加 载 的 src/ui/public/routes/route manager.js 
文件 里 ， 其 中 会 调用 
sr/ui/public/index_patterns/route_setup/load_default.js 中 提供 的 
addSetupwork 方法 ， 在 未 设置 default index pattern 的 时 候 跳 转 URL 到 


whenMissingRedirectTo 页 面 。 


uiRoutes 
.addSetupWork(...) 
.afterWork( 

// success 

null, 


// failure 
function (err, kbnUrl) { 
let hasDefault = !(err instanceof NoDefaultIndexPattern); 
if (hasDefault || !whenMissingRedirectTo) throw err; // r 
ethrow 


kbnUrl.change(whenMissingRedirectTo); 
if (!defaultRequiredToasts) defaultRequiredToasts - []; 
else defaultRequiredToasts.push(notify.error(err)); 


而 这 个 whenMissingRedirectTo 页 面 是 在 kibana 应 用 的 源码 里 写 死 的 ， 见 


src/core_plugins/kibana/public/management/index.js 


uiRoutes 
.when('/management', { 
template: landingTemplate 


3) 


require('ui/index patterns/route setup/load default')(( 
whenMissingRedirectTo: '/management/kibana/index' 


}); 


在 原先 的 版 本 中 ，routes 里 面 还 会 检查 Elasticsearch 的 版 本 号 ， 在 5.0 版 里 ， 这 
件 事 情 从 kibana plugin 改 到 elasticsearch plugin 里 完成 了 。 


courier 概述 


kibana.js 32 ° A SRAM  application.load 事件 ， 在 页 面 加 载 完 成 的 
时 候 触 发 courier.start() Wee 


src/ui/public/courier/courier.js 中 定义 了 Courier 类 。Courier 是 一 个 非 
常 重要 的 东西 ， 可 以 简单 理解 为 kibana 跟 ES 之 间 的 一 个 object mapper。 简 要 的 
说 ， 包 括 一 下 功能 : 


import DocSourceProvider from './data_source/doc_source'; 


function Courier() { 
var self = this; 
var DocSource = Private(DocSourceProvider); 
self.DocSource = DocSource; 


self.start = function () { 
searchLooper.start(); 
docLooper.start(); 
return this; 
J; 
self.fetch = function () { 
fetch.fetchQueued(searchStrategy).then(function () { 
searchLooper.restart(); 
3); 
self.started = function () { 
return searchLooper.started(); 
J; 
self.stop = function () { 
searchLooper.stop(); 
return this; 
J; 
self.createSource = function (type) { 
switch (type) { 
case 'doc': 
return new DocSource(); 
case 'search': 
return new SearchSource(); 


j 

H 

self.close = function () { 
searchLooper.stop(); 
docLooper.stop(); 


_.invoke(requestQueue, 'abort'); 


if (requestQueue.length) { 
throw new Error('Aborting all pending requests failed. 


从 类 的 方法 中 可 以 看 出 ， 其 实 主要 就 是 五 个 属性 的 控制 : 


e DocSource 和 SearchSource : 继承 自 
src/ui/public/courier/data source/ abstract.js ， 调 用 
src/ui/public/courier/data source/data source/ doc send to es.j: 
完成 跟 ES 数据 的 交互 ， 用 来 做 savedObject 和 index pattern $93 5 : 





es[method] (params) 
.then(function (resp) { 
if (resp.status === 409) throw new errors.VersionConflic 
t(resp); 


doc. storeVersion(resp. version); 
doc.id(resp. id); 


var docFetchProm; 


if (method !-- 'index') { 
docFetchProm - doc.fetch(); 
} else { 


// we already know what the response will be 
docFetchProm = Promise.resolve({ 

_id: resp._id, 

_index: params.index, 

_source: body, 

_type: params.type, 

_version: doc. getVersion(), 

found: true 


}); 


这 个 es 在 是 调用 了 src/ui/public/es.js 里 定义 的 service? € i A ÈRA ij 
单 ， 就 是 加 载 官 方 的 elasticsearch.js 库 ， 然 后 初始 化 一 个 最 简 的 esFactory 客户 
端 ， 包 括 超时 都 设 成 了 0， 把 这 个 控制 交 给 server 端 。 


import 'elasticsearch-browser'; 
import _ from 'lodash'; 
import uiModules from 'ui/modules'; 


let es; // share the client amongst all apps 
uiModules 
.get('kibana', ['elasticsearch', 'kibana/config' ] ) 
.service('es', function (esFactory, esUrl, $q, esApiVersion, e 
sRequestTimeout) { 
if (es) return es; 
es = esFactory({ 


host: esUrl, 
log: 'info', 
requestTimeout: esRequestTimeout, 
apiVersion: esApiVersion, 
plugins: [function (Client, config) { 
// esFactory automatically injects the AngularConnector 
to the config 
// https://github.com/elastic/elasticsearch-js/blob/mast 
er/src/lib/connectors/angular.js 
_.class(CustomAngularConnector).inherits(config.connecti 
onClass); 
function CustomAngularConnector(host, config) { 
CustomAngularConnector.Super.call(this, host, config); 


this.request = _.wrap(this.request, function (request, 
params, cb) { 
if (String(params.method).toUpperCase() === 'GET') ( 
params.query = _.defaults({ _: Date.now() }, params 
.query); 
j 
return request.call(this, params, cb); 
3); 
j 


config.connectionClass - CustomAngularConnector; 


3] 
+); 


return es; 


3): 


e searchLooper 和 docLooper : 分 别 给 Looper.start 方法 传递 
searchStrategy 和 docStrategy， 对 应 ES 4 /_msearch 和 / mget 请 
求 。searchLooper 的 实现 如 下 : 


import FetchProvider from '../fetch'; 

import SearchStrategyProvider from '../fetch/strategy/search'; 
import RequestQueueProvider from '../ request queue'; 

import LooperProvider from './ looper'; 


export default function SearchLooperService(Private, Promise, 
tifier, $rootScope) { 

let fetch - Private(FetchProvider); 

let searchStrategy - Private(SearchStrategyProvider); 

let requestQueue - Private(RequestQueueProvider); 


let Looper - Private(LooperProvider); 
let searchLooper = new Looper(null, function () { 
$rootScope.$broadcast('courier:searchRefresh'); 
return fetch.these( 
requestQueue.getInactive(searchStrategy ) 
); 
3); 


这 里 的 关键 方法 是 fetch.these() > HA 
src/ui/public/courier/fetch/fetch these.js ， 其 中 调用 的 
src/ui/public/courier/fetch/call_client.js 有 如 下 一 段 代码 : 


No 


Promise.map(executable, function (req) { 
return Promise.try(req.getFetchParams, void 0, req) 
.then(function (fetchParams) { 
return (req.fetchParams = fetchParams); 
3); 
}) 


.then(function (reqsFetchParams) { 
return strategy. reqsFetchParamsToBody(reqsFetchParams ) ; 


}) 
.then(function (body) { 


return (esPromise = es[strategy.clientMethod]({ body })) 


}) 
.then(function (clientResp) { 


return strategy.getResponses(clientResp); 


}) 
.then(respond) 


在 这 段 代 码 中 ， 我 们 可 以 看 到 strategy.reqsFetchParamsToBody() , 

strategy.getResponses() 和 strategy.clientMethod ， 正 是 之 前 
searchLooper 和 docLooper 传递 的 对 象 属性 。 而 最 终 发 送 请 求 ， 同 样 用 的 是 前 面 
解释 过 的 es 这 个 service ° 


此 外 ，Courier 还 提供 了 自动 刷新 的 控制 功能 : 


self.fetchInterval = function (ms) { 
searchLooper .ms(ms); 
return this; 


HH 


$rootScope.$watchCollection('timefilter.refreshInterval', 
function () { 
var refreshValue 


_.get($rootScope, 'timefilter.refresh 
Interval.value'); 


var refreshPause = _.get($rootScope, 'timefilter.refresh 
Interval.pause'); 
if ( .isNumber(refreshValue) && !refreshPause) { 
self.fetchInterval(refreshValue); 
) else { 
self.fetchInterval(0); 
j 
3); 


路 径 记 忆 功 能 的 实现 


src/ui/public/chrome/api/apps.js 中 ， 我 们 可 以 看 到 路 径 记 忆 功 能 是 怎么 
实现 的 : 


module.exports = function (chrome, internals) { 
internals.appUrlStore = internals.appUrlStore || window.sessio 
nStorage; 


chrome.getLastUrlFor = function (appId) { 
return internals.appUrlStore.getItem( appLastUrl:$[appId)'); 
3 
chrome.setLastUrlFor = function (appId, url) { 
internals.appUrlStore.setItem( appLastUrl:${appId}°, url); 


H 


这 里 使 用 的 sessionstorage 是 HTML5 自 带 的 新 特性 ， 这 样 ， 每 次 标签 页 切换 
的 时 候 ， 都 可 以 把 $location.url 保存 下 来 。 
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搜索 页 


前 文 已 经 说 到 ，kibana.js 中 依次 加 载 了 各 主要 功能 模块 的 入 口 。 比 如 搜索 页 是 
src/core plugins/kibana/public/discover/index.js °。 通 过 这 个 文件 路 径 
就 可 以 猜 到 ， 有 关 搜 索 页 的 功能 ， 代 码 应 该 都 在 
src/core plugins/kibana/public/discover/ 里 了 。 这 个 目录 下 的 文件 有 : 


e hit sort fn.js 

e components/ 

e controllers/ 

e directives/ 

e index.html 

e index.js 

e partials/ 

e saved searches/ 
e styles/ 


这 也 是 一 个 比较 标准 的 angular 模块 的 目录 结构 了 。 一 眼 就 能 知道 ，controller、 
directive 等 等 分 别 应 该 进 哪里 去 看 。 当 然 首先 第 一 步 还 是 看 index.js : 


import 'plugins/kibana/discover/saved searches/saved searches'; 
import 'plugins/kibana/discover/directives/no results'; 

import 'plugins/kibana/discover/directives/timechart'; 

import 'ui/collapsible sidebar'; 

import 'plugins/kibana/discover/components/field chooser/field c 
hooser'; 

import 'plugins/kibana/discover/controllers/discover'; 

import 'plugins/kibana/discover/styles/main.less'; 

import 'ui/doc table/components/table row'; 

import savedObjectRegistry from 'ui/saved objects/saved object r 
egistry'; 


savedObjectRegistry.register(require('plugins/kibana/discover/sa 
ved searches/saved search register')); 


已 存 搜索 、 事 件数 趋势 图 、 事 件 列 表 、 字 段 列 表 ， 各 自 载 入 了 。 下 面 可 以 看 一 下 这 
几 个 功能 点 的 实现 。 


plugins/kibana/discover/saved_searches/saved 
_searches.js 


e X 3. savedSearches 这 个 angular service， 用 来 操作 kbnlndex 索引 里 search 
这 个 类 型 下 的 数据 ; 

e 加 载 了 saved searches/ saved searches.js 提供 的 savedSearch 这 个 
angular factory， 这 里 定义 了 一 个 搜索 (search) Æ kbnindex 里 的 数据 结 
14 > &4& title, description, hits, column, sort, version 等 字段 (这 部 分 内 容 ， 可 
以 直接 通过 读 取 Elasticsearch 中 的 索引 内 容 看 到 ， 比 阅读 代码 更 直接 ， 本 章 
最 后 即 专门 介绍 kbnIndex 中 的 数据 结构 )， 看 的 是 不 是 有 点 眼熟 ? 没 错 ， 这 
个 savedSearch 就 是 继承 了 上 一 节 我 们 介绍 的 那个 courier 的 savedObject : 


module.factory('SavedSearch', function (courier) { 
_.Cclass(SavedSearch).inherits(courier.SavedObject); 
function SavedSearch(id) { 


e 还 加 载 并 注册 了 
plugins/kibana/management/saved object registry ， 表 示 可 以 在 
management 里 修改 这 里 的 savedSearches 对 象 。 


plugins/kibana/discover/directives/timechart.js 


e 加 载 ui/vislib 。 
e 提供 discoverTimechart 这 个 angular directive， 监 听 "data" 并 调用 
vislib.Chart 对 象 绘图 。 


vislib 是 整个 Kibana 可 视 化 的 实现 部 分 ， 下 一 节 会 更 详细 的 讲述 。 


plugins/kibana/discover/components/field_cho 
oser/field_chooser.js 


e 提供 discFieldChooser 这 个 angular directive， 其 中 监听 字段 和 事件 的 变化 ， 
并 调用 计算 常用 字段 排行 ， 


$scope. $watchMulti([ 
'[]fieldCounts', 
'[]columns', 


'[]hits' 
], function (cur, prev) { 
var newHits = cur[2] !== prev[2]; 
var fields = $scope.fields; 
var columns = $scope.columns || []; 


var fieldCounts = $scope.fieldCounts; 


if (!fields || newHits) { 
$scope.fields = fields = getFields(); 


} 

_.Chain(fields) 

.each(function (field) { 
field.displayOrder = _.indexOf(columns, field.name) 
field.display = !!field.displayOrder; 
field.rowCount = fieldCounts[field.name]; 

}) 

.sortBy(function (field) { 
return (field.count || 0) * -1; 

}) 


. groupBy (function (field) { 
if (field.display) return 'selected'; 


isplayOrder'); 


return field.count > © ? 'popular' : 'unpopular'; 

}) 

.tap(function (groups) { 
groups.selected = _.sortBy(groups.selected || [], 'd 
groups.popular = groups.popular || []; 
groups.unpopular = groups.unpopular || []; 


var extras = groups.popular.splice(config.get('field 


s:popularLimit')); 


groups.unpopular = extras.concat(groups.unpopular); 
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.each(function (group, name) { 


$scope[name + 'Fields'] = _.sortBy(group, name === ' 
selected' ? 'display' : 'name'); 
3) 
.commit(); 
$scope.fieldTypes = _.union([undefined],  .pluck(field 
s, 'type')); 
3); 


监听 "data" 并 调用 $scope.details() 方法 ， 


提供 $scope.vizLocation() 方法 。 方 法 中 ， 根 据 字 段 的 类 型 不 同 ， 分 别 可 能 使 
用 date histogram / geohash grid / terms 聚合 函数 ， 创 建 可 视 化 模型 ， 然 
后 带 着 当前 页 这 些 设 定 一 一 前 面 说 过 ， 各 app 之 问 通过 globalState 共享 状态 ， 也 
wiz URL 中 的 ?_a=(...) 。 各 app 会 通过 
rison.decode($location.search()._a) 和 
rison.encode($location.search()._a) 设置 和 读 取 一 一 跳 转 到 
"/visualize/create" 页 面 ， 相 当 于 是 这 三 个 常用 聚合 的 快速 可 视 化 操作 。 


默认 的 create 页 的 rison 如 下 : 


return '#/visualize/create?' + $.param(_.assign($locat 


ion.search(), { 
indexPattern: $scope.state.index, 
type: type, 
_a: rison.encode({ 
filters: $scope.state.filters || [], 
query: $scope.state.query || undefined, 
Visto 
type: type, 
aggs: [ 
agg, 
(schema: 'metric', type: 'count', 'id': '2'} 


之 前 章节 的 ul 示例 中 ， 读 者 如 果 注 意 的 话 ， 会 发 现 id 是 从 2 开始 的 ， 原 因 即 在 
此 。 


e 加载 
plugins/kibana/discover/components/field_chooser/lib/field_calc 
ulator.js ， 提 供 fieldCalculator.getFieldValueCounts() 方法 ， 在 
$scope.details() 中 读 取 被 点 击 的 字段 值 的 情况 。 
e 加 载 
plugins/kibana/discover/components/field_chooser/discover_field 
.js ， 提 供 discoverField 这 个 angular directive， 用 于 弹出 浮 层 展示 临时 的 
visualize( 调 用 上 一 条 提供 的 $scope.details() 方法 )， 同 时 给 被 点 击 的 字 
段 加 常用 度 ; mR 
plugins/kibana/discover/components/field_chooser/lib/detail_vie 
ws/string. html 网 页 ， 用 于 浮 层 效果 。 网 页 中 对 indexed X scripted 类 型 的 
字段 ， 可 以 调用 前 面 提 到 的 vizLocation() 方法 。 


import detailsHtml from 'plugins/kibana/discover/compone 
nts/field chooser/lib/detail views/string.html'; 
$scope.toggleDetails = function (field, recompute) { 
if ( .isUndefined(field.details) || recompute) { 
// This is inherited from fieldChooser 
$scope.details(field, recompute); 
detailScope.$destroy(); 
detailScope = $scope.$new(); 
detailScope.warnings = getWarnings(field); 


detailsElem = $(detailsHtml); 
$compile(detailsElem)(detailScope); 
$elem.append(detailsElem).addClass('active'); 

) else { 
delete field.details; 
detailsElem.remove(); 
$elem.removeClass('active'); 

j 

3 


e 加 载 并 泻 染 


plugins/kibana/discover/components/field chooser/field chooser. 


html 网 页 。 网 页 中 使 用 了 上 一 条 提供 的 discover-field » 


plugins/kibana/discover/controllers/discover.js 


加 载 了 诸多 js， 主 要 做 了 : 
e A "/discover/:id?" 提供 route 并 加 载 plugins/discover/index.html 网 
He 
e 提供 discoverApp 这 个 angular controller ° 
e 加 载 ui/vis.js 并 在 setupVisualization 函数 中 绘制 histogram 图 。 


var visStateAggs = [ 
{ 
type: ‘count’, 
schema: 'metric' 
ty 
{ 
type: 'date histogram', 
schema: 'segment', 
params: { 
field: $scope.opts.timefield, 
interval: $state.interval 


} 
1; 


$scope.vis = new Vis($scope.indexPattern, { 
title: savedSearch.title, 
type: 'histogram', 
params: ( 
addLegend: false, 
addTimeMarker: true 
i 
listeners: ( 
click: function (e) { 
timefilter.time.from - moment(e.point.x); 
timefilter.time.to = moment(e.point.x + e.data.order 
ed.interval); 
timefilter.time.mode - 'absolute'; 
tr 
brush: brushEvent 
ty 
aggs: visStateAggs 
3); 


$scope.searchSource.aggs(function () ( 
$scope.vis.requesting(); 
return $scope.vis.aggs.toDsl(); 
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visualize 


index.js 中 ， 首 要 当然 是 注册 自己 。 此 外 ， 还 加 载 两 部 分 功 

能 : plugins/kibana/visualize/editor/* 和 
plugins/kibana/visualize/wizard/wizard.js 。 然 后 定义 了 一 个 route， 默 

认 跳 转 /visualize 到 /visualize/step/1 ° 


editor 


editor.js 中 也 定义 了 两 个 route， 分 别 是 /visualize/create 和 
/visualize/edit/:id 。 然 后 还 定义 了 一 个 controller， 叫 VisEditor ， 对 应 
的 HTML 是 plugins/kibana/visualize/editor/editor.html ， 其 中 用 到 两 
个 directive， 分 别 是 visualize 和 vis-editor-sidebar 。 


其 中 create 是 先 加 载 ui/registry/vis_types ， 并 检查 
$route.current.params.type 是 否 存在 ， 然 后 调用 
savedVisualizations.get($route.current.params) 方法 ; 而 edit 是 直接 调 


用 savedVisualizations.get($route.current.params.id) ° 


vis_types 


实际 注册 了 vis types 的 地 方 包 括 : 


plugins/table_vis/index.js 

e plugins/metric_vis/index.js 

e plugins/markdown vis/index.js 
plugins/kbn vislib vis types/index.js 


前 三 个 是 表单 ， 最 后 一 个 是 可 视 化 图 。 内 容 如 下 : 


import visTypes from 'ui/registry/vis types'; 
visTypes.register(require('plugins/kbn vislib vis types/histogra 
m')); 
visTypes.register(require('plugins/kbn vislib vis types/line')); 
visTypes.register(require('plugins/kbn vislib vis types/pie')); 
visTypes.register(require('plugins/kbn vislib vis types/area')); 
visTypes.register(require('plugins/kbn vislib vis types/tile map 
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以 histogram 为 例 解 释 一 下 visTypes。 下 面 的 实现 较 长 ， 我 们 拆 成 三 部 分 : 


第 一 部 分 ， 加 载 并 生成 VislibVisType 对 象 : 


import VislibVisTypeVislibVisTypeProvider from 'ui/vislib vis ty 
pe/vislib vis type'; 

import VisSchemasProvider from 'ui/vis/schemas'; 

import histogramTemplate from 'plugins/kbn vislib vis types/edit 
ors/histogram.html'; 


export default function HistogramVisType(Private) { 

const VislibVisType - Private(VislibVisTypeVislibVisTypeProvid 
er); 

const Schemas - Private(VisSchemasProvider); 


return new VislibVisType({ 

name: 'histogram', 

title: 'Vertical bar chart', 

icon: 'fa-bar-chart', 

description: 'The goto chart for oh-so-many needs. Great for 
time and non-time data. Stacked or grouped, ' + 

'exact numbers or percentages. If you are not sure which cha 
rt you need, you could do worse than to start here.', 


第 二 部 分 ，histogram 可 视 化 所 接受 的 参数 默认 值 以 及 对 应 的 参数 编辑 页 面 : 


params: { 
defaults: { 
shareYAxis: true, 
addTooltip: true, 
addLegend: true, 
legendPosition: 'right', 
scale: 'linear', 
mode: 'stacked', 
times: [], 
addTimeMarker: false, 
defaultYExtents: false, 
setYExtents: false, 
yAxis: {} 
tr 
scales: ['linear', 'log', 'square root'], 
modes: ['stacked', 'percentage', 'grouped'], 
editor: histogramTemplate 


ty 


第 三 部 分 ，histogram 可 视 化 能 接受 的 Schema » — A X, > metric 数值 聚合 肯定 


X Y 44; bucket 聚合 肯定 是 X 44; 而 在 此 基础 上 ，Kibana4 还 可 以 让 bucket 有 不 
同 效果 ， 也 就 是 Schema 里 的 segment( RU), group 和 split。 根 据 效果 不 同 ， 这 
里 是 各 有 增 减 的 ， 比 如 饼 图 就 不 会 有 group e 


schemas: new Schemas([ 


{ 


group: 'metrics', 
name: 'metric', 

title: 'Y-Axis', 

min: 1, 

aggFilter: '!std dev', 
defaults: [ 


{ schema: 'metric', type: 


group: 'buckets', 

name: 'segment', 

title: 'X-Axis', 

min: 0, 

max: 1, 

aggFilter: '!geohash grid' 


group: 'buckets', 

name: 'group', 

title: 'Split Bars', 

min: O0, 

max: 1, 

aggFilter: '!geohash grid' 


group: 'buckets', 

name: 'split', 

title: 'Split Chart', 

min: 0, 

max: 1, 

aggFilter: '!geohash grid' 


'count' } 


这 里 使 用 的 VislibVisType 类 ， 继 承 自 ui/vis/VisType.js > VisType.js 内 容 如 
Ts 


import VisSchemasProvider from 'ui/vis/schemas'; 


export default function VisTypeFactory(Private) { 
let VisTypeSchemas - Private(VisSchemasProvider); 


function VisType(opts) ( 
opts = opts || {}; 


this.name = opts.name; 

this.title = opts.title; 

this.responseConverter = opts.responseConverter; 
this.hierarchicalData = opts.hierarchicalData || false; 
this.icon = opts.icon; 

this.description = opts.description; 


this.schemas = opts.schemas || new VisTypeSchemas(); 
this.params = opts.params || {}; 
this.requiresSearch = opts.requiresSearch == null ? true : o 


pts.requiresSearch; // Default to true unless otherwise specifie 
d 


return VisType; 


3 
基本 跟 上 面 histogram 的 示例 一 致 ， 注 意 这 里 面 的 responseConverter 和 
hierarchicalData， 是 给 不 同 的 visType 做 相应 数据 转换 的 。 在 实际 的 VislibVisType 
中 ， 就 有 下 面 一 段 : 
if (this.responseConverter == null) { 


this.responseConverter = pointSeries; 


可 见 默认 情况 下 ，Kibana 是 尝试 把 聚合 结果 转换 成 点 线 图 数组 的 。 


VislibVisType 中 另 一 部 分 ， 则 是 扩展 了 一 个 自己 的 方法 createRenderbot > M + 
成 VislibRenderbot 对 象 。 这 个 类 的 实现 在 
ui/vislib vis type/vislib renderbot.js ， 其 中 最 关键 的 几 行 是 : 


import VislibVisTypeBuildChartDataProvider from 'ui/vislib vis t 
ype/build chart data'; 
module.exports - function VislibRenderbotFactory(Private, $injec 
tor) { 

let buildChartData = Private(VislibVisTypeBuildChartDataProvid 
er); 


self.vislibVis = new vislib.Vis(self.$el[0], self.vislibPara 
ms); 


VislibRenderbot.prototype.buildChartData = buildChartData; 
VislibRenderbot.prototype.render = function (esResponse) { 
this.chartData = this.buildChartData(esResponse); 
return AngularPromise.delay(1).then(() => { 
this.vislibVis.render(this.chartData, this.uiState); 
3); 
3 


也 就 是 说 ， 分 为 两 部 分 ，buildChartData 方法 和 vislib.Vis 对 象 。 


先 来 看 buildChartData 的 实现 : 


import AggResponseIndexProvider from 'ui/agg response/index'; 


return function (esResponse) ( 
let vis - this.vis; 
if (vis.isHierarchical()) { 
return aggResponse.hierarchical(vis, esResponse); 
} 
let tableGroup = aggResponse.tabify(vis, esResponse, { 
canSplit: true, 
asAggConfigResults: true 
}); 
let converted = convertTableGroup(vis, tableGroup); 
if (!converted) { 
converted = { rows: [] }; 
} 
converted.hits = esResponse.hits.total; 
return converted; 


Fr 


function convertTable(vis, table) { 
return vis.type.responseConverter(vis, table); 


又 看 到 responseConverter 和 hierarchical 两 个 熟悉 的 字眼 了 ， 不 过 这 回 是 另 一 个 
对 象 的 方法 ， 那 么 我 们 继续 跟踪 下 去 ， 看 看 这 个 aggResponse 类 是 怎么 回 事 : 


import AggResponseHierarchicalBuildHierarchicalDataProvider from 
'ui/agg response/hierarchical/build hierarchical data'; 

import AggResponsePointSeriesPointSeriesProvider from 'ui/agg re 

sponse/point series/point series'; 

import AggResponseTabifyTabifyProvider from 'ui/agg response/tab 

ify/tabify'; 

import AggResponseGeoJsonGeoJsonProvider from 'ui/agg response/g 

eo json/geo json'; 


export default function NormalizeChartDataFactory(Private) ( 
return { 
hierarchical: Private(AggResponseHierarchicalBuildHierarchic 
alDataProvider), 
pointSeries: Private(AggResponsePointSeriesPointSeriesProvid 
er), 
tabify: Private(AggResponseTabifyTabifyProvider), 
geoJson: Private(AggResponseGeoJsonGeoJsonProvider) 
3 
3 


然后 我 们 看 vislib.Vis *I £& > CL ui/public/vislib/vis.js 里 。 同 时 我 们 注 
意 到 ， 定 义 vislib 这 个 服务 的 ui/public/vislib/index.js 里 ， 还 导入 了 一 个 
模块 ， 叫 d3， 没 错 ， 我 们 离 真 正 的 绘图 越 来 越 近 了 。 


vis.js 中 加 载 了 ui/vislib/lib/handler/handler types 和 


ui/vislib/visualizations/vis_types 


import VislibLibHandlerHandlerTypesProvider from 'ui/vislib/lib/ 
handler/handler_types'; 
import VislibVisualizationsVisTypesProvider from 'ui/vislib/visu 
alizations/vis_types'; 


chartTypes 用 来 定义 图 : 


class Vis extends Events { 
constructor($el, config) { 
super (arguments); 
this.el = $el.get ? $el.get(0) : $el; 
this.binder = new Binder(); 
this.ChartClass = chartTypes[config.type]; 


this. attr = _.defaults({}, config || {}, { 
legendOpen: true 
3): 


接着 是 handlerTypes 用 来 绘制 图 : 


render(data, uiState) { 
var chartType = this._attr.type; 
this.data = data; 
this.handler = handlerTypes[chartType](this) || handlerTyp 
es.column(this); 
this. runWithoutResizeChecker('render'); 


Hh 


_runWithoutResizeChecker(method) { 
this.resizeChecker.stopSchedule(); 
this. runOnHandler(method); 
this.resizeChecker.saveSize(); 
this.resizeChecker.saveDirty(false); 
this.resizeChecker.continueSchedule(); 

3 

runOnHandler = function (method) { 

this.handler[method](); 


}; 


ui/vislib/lib/handler/handler types 中 ， 根 据 不 同 的 vis_types， 分 别 返 
回 不 同 的 处 理 对 象 ， 主 要 出 自 ui/vislib/lib/handler/types/point_series , 
ui/vislib/lib/handler/types/pie 和 
ui/vislib/lib/handler/types/tile map 。 比 如 histogram 就 是 
pointSeries.column 。 可 以 看 到 point series.js 中 ， 对 column 是 加 上 了 
zeroFill:true, expandLastBucket:true 两 个 参数 调用 create() 方法 。 


而 create() 方法 里 的 new Handler() 传递 的 ， 显 然 就 是 给 d3.js 的 绘图 参 
数 。 而 Handler 具体 初始 化 和 泻 染 过 程 ， 则 在 被 加 载 的 
ui/vislib/lib/handler/handler.js 中 。 Handler.prototype.render 中 
如 下 一 段 : 


const selection = d3.select(this.el); 
const chartSelection = selection..selectAll('.chart'); 
chartSelection.each(function (chartData) ( 
const chart = new self.ChartClass(self, this, chartData); 
self.vis.activeEvents().forEach(function (event) { 
self.enable(event, chart); 


3); 
binder.on(chart.events, 'rendered', () => { 
loadedCount++; 
if (loadedCount === chartSelection.length) { 
charts[0].events.emit('renderComplete'); 
} 
}); 


charts.push(chart); 
chart.render(); 


3): 


这 里 面 的 Chartclass() 就 是 在 vislib.js 中 加 载 了 的 
ui/vislib/visualizations/vis types 。 它 会 根据 不 同 的 vis_types， 分 别 返 
回 不 同 的 可 视 化 对 和 象 ， 包 括 : ui/vislib/visualizations/column chart , 
ui/vislib/visualizations/pie_chart 
ui/vislib/visualizations/line_chart , 
ui/vislib/visualizations/area_chart 和 


ui/vislib/visualizations/tile_map ° 


这 些 对 象 都 有 同一 个 基 类 : ui/vislib/visualizations/_chart ^ HPARA 


一 段 : 


render() { 
const selection = d3.select(this.chartEl); 


selection.selectAll('*').remove( ); 
selection.call(this.draw()); 


m 


也 就 是 说 ， 各 个 可 视 化 对 象 ， 只 需要 用 d3.js 或 者 其 他 绘图 库 ， 完 成 自己 的 draw() 
函数 ， 就 可 以 了 | 


draw 函数 的 实现 一 般 格 式 ， 就 像 下 面 这 段 出自 LineChart 的 代码 : 


draw() { 
const self = this; 
const $elem = $(this.chartEl); 
const margin = this._attr.margin; 
const elWidth = this. attr.width = $elem.width(); 
const elHeight = this._attr.height = $elem.height(); 
const scaleType = this.handler.yAxis.getScaleType(); 
const yScale = this.handler.yAxis.yScale; 
const xScale = this.handler.xAxis.xScale; 
const minwidth = 20; 
const minHeight = 20; 
const startLineX = 0; 
const lineStrokeWidth - 1; 
const addTimeMarker - this. attr.addTimeMarker; 
const times - this. attr.times || []; 
let timeMarker; 


return function (selection) { 
selection.each(function (data) ( 
const el - this; 
const layers = data.series.map(function mapSeries(d) { 
const label = d.label; 
return d.values.map(function mapValues(e, i) ( 
return { 
_input: e, 
label: label, 
x: self. attr.xValue.call(d.values, e, i), 


y: self._attr.yValue.call(d.values, e, i) 
3 
3); 
3); 
const width - elWidth - margin.left - margin.right; 
const height - elHeight - margin.top - margin.bottom; 
const div - d3.select(el); 
const svg = div.append('svg') 
.attr('width', width + margin.left + margin.right) 
.attr('height', height + margin.top + margin.bottom) 
.append('g' ) 
.attr('transform', 'translate(' + margin.left + ',' + 
margin.top + ')'); 


// 处 理 data 到 svg 上 


self.events.emit('rendered', { 
chart: data 


}); 


return svg; 


3): 
ds 
jen 


当然 ， 为 了 代码 逻辑 ， 有 些 比 较 复 杂 的 绘制 ， 还 是 会 继续 拆 分 成 其 他 文件 的 。 比 如 
leaflet 地 图 ， 就 是 在 ui/vislib/visualizations/tile_map 里 加 载 的 


ui/vislib/visualizations/_map.js 完成 。 


从 数据 到 d3 泻 染 ， 要 经 过 的 主要 流程 就 是 这 样 。 如 果 打 算 自己 亲手 扩展 一 个 新 的 
可 视 化 方案 的 读者 ， 可 以 具体 参考 我 实现 的 sankey 

图 : https://github.com/chenryn/kibana4/commit/4e0bcbeb4c8fd94807c3a0b1df2a 
c6f56634f9a5 


savedVisualizations 


这 个 类 在 
core_plugins/kibana/public/visualize/saved_visualizations/saved_vis 
ualizations.js 里 定义 。 其 中 分 三 步 ， 加 载 


core_plugins/kibana/public/visualize/saved_visualizations/_saved_vi: 
， 注 册 到 plugins/kibana/management/saved object registry ， 以 及 定义 
一 个 angular service "| savedVisualizations ° 


plugins/kibana/visualize/saved visualizations/ saved vis 里 是 定义 一 
个 angular factory "| Savedvis 。 这 个 类 继承 自 courier.SavedObject ， 主 要 有 
_getLinkedSavedSearch 方法 调用 savedSearches 获取 在 discover 中 保存 的 
search 对 象 ， 以 及 visState 属性 。 该 属性 保存 了 visualize 定义 的 JSON 数据 。 


savedVisualizations 里 主要 就 是 初始 化 SavedVis 对 象 ， 以 及 提供 了 一 个 find 搜索 
方法 。 整 个 实现 和 上 一 节 讲 的 savedSearches 基本 一 样 ， 就 不 再 讲 了 。 


Visualize 


这 个 directive 在 ui/visualize/visualize.js 中 定义 。 而 我 们 可 以 上 拉 看 到 的 
请 求 、 响 应 、 表 格 、 性 能 数据 ， 则 使 用 的 是 ui/visualize/spy/spy.js 中 定义 
4) 4— directive visualizeSpy ° 


visualize.html 上 定义 了 一 个 普通 的 div， 其 class X visualize-chart > # 
visualize.js 中 ， 通 过 getter('.visualize-chart') 方法 获取 div 元 素 : 


function getter(selector) { 
return function () { 
let $sel = $el.find(selector); 
if ($sel.size()) return $sel; 
H 
} 


let getVisEl = getter('.visualize-chart'); 


然后 创建 一 个 renderbot : 


$scope.$watch('vis', prereq(function (vis, oldVis) { 


let $visEl - getVisEl(); 
if (!$visEl) return; 


if (lattr.editableVis) ( 
$scope.editableVis - vis; 


if (oldVis) $scope.renderbot - null; 
if (vis) $scope.renderbot - vis.type.createRenderbot(v 


is, $visEl); 


})); 
最 后 在 searchSource 对 象 变化 ， 即 有 新 的 搜索 响应 返回 时 ， 完 成 泻 染 : 
prereq(function (searchSou 


$scope.$watch('searchSource', 


rce) { 
if (!searchSource || attr.esResp) return; 


searchSource.onResults().then(function onResults(resp) 


if ($scope.searchSource !== searchSource) return; 


$scope.esResp = resp; 


return searchSource.onResults().then(onResults); 


}).catch(notify.fatal); 
searchSource.onError(notify.error).catch(notify.fatal) 


})); 


$scope.$watch('esResp', prereq(function (resp, prevResp) 


if (!resp) return; 
$scope.renderbot.render (resp); 


})); 


VisEditorSidebar 


这 个 directive 在 plugins/kibana/visualize/editor/sidebar.js 中 定义 。 对 
应 的 HTML € plugins/kibana/visualize/editor/sidebar.html ， 其 中 又 用 
到 两 个 directive， 分 别 是 vis-editor-agg-group 和 vis-editor-vis- 
options 。 它 们 分 别 有 sidebar.js 加 载 的 
plugins/kibana/visualize/editor/agg group 和 
plugins/kibana/visualize/editor/vis options 提供 。 然 后 继续 HTML -> 

directive 下 去 ， 基 本 上 plugins/kibana/visualize/editor/ 目录 下 那 堆 
agg*.js 和 agg*.html 都 是 做 这 个 用 的 。 


其 中 比较 有 意思 的 ， 应 该 算是 agg add.js 。 我 们 都 知道 ，K4 最 大 的 特点 就 是 可 
以 层 司 子 聚 合 ， 这 个 操作 就 是 在 这 里 完成 的 : 


import VisAggConfigProvider from 'ui/vis/agg config'; 

import uiModules from 'ui/modules'; 

import aggAddTemplate from 'plugins/kibana/visualize/editor/agg _- 
add.html'; 


uiModules 

.get('kibana') 

.directive('visEditorAggAdd', function (Private) { 
const AggConfig - Private(VisAggConfigProvider); 


return { 
restrict; "E, 
template: aggAddTemplate, 
controllerAs: 'add', 
controller: function ($scope) { 
const self - this; 


self.form - false; 
self.submit = function (schema) { 
self.form - false; 


const aggConfig = new AggConfig($scope.vis, { 
schema: schema 


T); 


aggConfig.brandNew = true; 
$scope.vis.aggs.push(aggConfig); 


id 


3) 


另 一 个 比较 重要 的 是 
core_plugins/kibana/public/visualize/editor/agg_params.js 。 其 中 加 
® J ui/agg types/index.js ， 又 监听 了 "agg.type" 变量 ， 也 就 是 实现 了 选择 
不 同 的 agg types 时 ， 提 供 不 同 的 agg params 选项 。 比 方 说 ， 选 择 
date_histogram， 字 段 就 只 能 是 Qtimestamp 这 种 date 类 型 的 字段 。 


ui/agg types/index.js 中 定义 了 所 有 可 选 agg_types $9 X ° HP metrics & 
4& : count, avg, sum, min, max, std deviation, cardinality, percentiles, 
percentile rank > HALIM G4  ui/agg types/metrics/ 目录 下 的 同名 .js 
文件 里 ; buckets 包括 : date histogram, histogram, range, date range, ip range, 
terms, filters, significant terms, geo_hash， 具 体 实现 分 别 存 在 
ui/agg_types/buckets/ 目录 下 的 同名 .js 文件 里 。 


这 些 类 定义 中 ， 都 有 比较 类 似 的 格式 ， 其 中 params 数组 的 第 一 个 元 素 ， 都 是 类 似 
这 样 


mt 


name: 'field', 
filterFieldTypes: 'string' 


terms.js 里 还 多 了 一 行 scriptable: true > "H filterFieldTypes 是 数组 。 


name: 'field', 

scriptable: true, 

filterFieldTypes: ['number', 'boolean', 'date', 'ip', 
'string'] 


j 


这 个 filterFieldTypes 在 ui/vis/ agg config.js 中， 通过 
fieldTypeFilter(this.vis.indexPattern.fields, 
fieldParam.filterFieldTypes); 得 到 可 选 字段 列表 。fieldTypeFilter 的 具体 实 
现在 filters/filed type.js 中 。 


wizard 


wizard.js 中 提供 两 个 route 和 对 应 的 controller ° 7%] /visualize/step/1 对 
应 VisualizeWizardStep1 * /visualize/step/2 对 应 
VisualizeWwizardStep2 。 这 两 个 的 最 终结 果 ， 都 是 跳 转 到 


/visualize/create?type=* 下 。 


visualize ff 47 


608 


dashboard 


plugins/kibana/public/dashboard/index.js 结构 跟 visualize 类 似 ， 设 置 两 
个 调用 savedDashboards.get() 方法 的 routes > 4& ££ — 4- "| dashboard-app 的 
directive ° 


savedDashboards 由 

plugins/kibana/public/dashboard/services/saved dashboard.js 提供 ， 
调用 es.search 获取 数据 ， 生 成 savedDashboard 对 象 ， 这 个 对 象 同样 也 是 继承 
savedObject， 主 要 内 容 是 panelsJSON 数组 字段 。 实 现 如 下 : 


module.factory('SavedDashboard', function (courier) { 
_.Class(SavedDashboard).inherits(courier.SavedObject); 
function SavedDashboard(id) { 
SavedDashboard.Super.call(this, ( 
type: SavedDashboard.type, 
mapping: SavedDashboard.mapping, 
searchSource: SavedDashboard.searchsource, 


stkojs eto) 

defaults: ( 
title: 'New Dashboard', 
hits: 0, 
description: '', 


panelsJSON: '[]', 
optionsJSON: angular.toJson({ 
darkTheme: config.get('dashboard:defaultDarkTheme') 
3) 
uistateJSON: '{}', 
version: 1, 
timeRestore: false, 
timeTo: undefined, 
timeFrom: undefined, 
refreshInterval: undefined 


clearSavedIndexPattern: true 


+); 


可 以 注意 到 ， 这 个 panelsJSON 是 一 个 字符 串 ， 这 跟 之 前 kbnindex 提 到 的 是 一 致 
的 o 


dashboard-app 中 ， _ ， 是 监听 搜索 框 和 过 滤 条 件 的 变更 ， 我 们 可 以 看 
到 init 函数 中 有 下 面 这 


function updateQueryOnRootSource() { 

var filters = queryFilter.getFilters(); 

if ($state.query) { 
dash.searchSource.set('filter', _.union(filters, [{ 

query: $state. query 

31)); 

} else { 
dash.searchSource.set('filter', filters); 


$scope.$listen(queryFilter, 'update', function () { 
updateQueryOnRootSource(); 
$state.save(); 


}); 


在 index.html 里 ， 实 际 承载 面板 的 ， 是 下 面 这 行 


<dashboard-grid></dashboard-grid> 


这 也 是 一 个 angular directive， 通 过 加 载 
plugins/kibana/public/dashboard/directives/grid.js 引入 的 。 其 中 添加 
面板 相关 的 代码 有 两 部 分 : 


$scope.$watchCollection('state.panels', function (pane 
ist 
const currentPanels = gridster.$widgets.toArray().ma 
p(function (el) { 
return getPanelFor(el); 


3); 
const removed - .difference(currentPanels, panels); 
const added = .difference(panels, currentPanels); 


if (added.length) added.forEach(addPanel); 


这 段 用 来 监听 $state.panels 数组 ， 一 旦 有 新 增 面 板 ， 调 用 addPanel % 
数 。 同 理 也 有 删除 面板 的 ， 这 里 就 不 重复 贴 了 。 


而 addPanel 42489 ZMK Sce F : 


var addPanel = function (panel) { 
_.defaults(panel, { 
size_x: 3, 
size y: 2 


}); 


panel.$scope = $scope.$new(); 

panel.$scope.panel = panel; 

panel.$el = $compile('«li»«dashboard-panel»«/li»')(pan 
el.$scope); 

gridster.add widget(panel.$el, panel.size x, panel.siz 
e y, panel.col, panel.row); 


UD 


这 里 即 验证 了 之 前 kbnindex «^ P49 gridster 默认 大 小 ， 又 引入 了 一 个 新 的 
directive > ^| dashboard-panel ° 


dashboard-panel 在 


plugins/kibana/public/dashboard/components/panel/panel.js 中 实现 ， 
其 中 使 用 了 


plugins/kibana/public/dashboard/components/panel/panel.html 页 面 。 
页 面 最 后 是 这 么 一 段 : 


<visualize ng-switch-when="visualization" 
vis="saved0bj.vis" 
search-sourcez'savedObj.searchSource" 
class="panel-content"> 

</visualize> 


«doc-table ng-switch-whenz"search" 
search-source="Saved0bj.searchSource" 
sorting="panel.sort" 
columns="panel.columns" 
class="panel-content" 
filter="filter"> 

</doc-table> 


这 里 使 用 的 savedObj A £& > KA 

plugins/kibana/public/dashboard/components/panel/lib/load panel.js 
获取 的 savedSearch 或 者 savedVisualization。 获 得 的 对 象 ， 以 
savedVisualization 为 例 : 


define(function (require) { 
return function visualizationLoader(savedVisualizations, Priva 
te) { // Inject services here 
return function (panel, $scope) { 
return savedVisualizations.get(panel.id) 
.then(function (savedVis) { 


savedVis.vis.listeners.click filterBarClickHandler($ 
scope.state); 


savedVis.vis.listeners.brush - brushEvent; 


return { 
savedObj: savedVis, 
panel: panel, 
editUrl: savedVisualizations.urlFor(panel.id) 
3): 
J; 
J; 
}); 


而 visualize 和 doc-table 两 个 directive。 这 两 个 正 是 之 前 在 visualize 和 discover 
插件 解析 里 提 到 过 的 ， 在 components/ 底下 实现 。 


Kibana 插件 


Kibana 从 4.2 以 后 ， 引 入 了 完善 的 插件 化 机 制 。 目 前 分 为 app，Vvistype > 
fieldformatter、spymode 等 多 种 插件 类 型 。 原 先 意义 上 的 Kibana 现在 已 经 变 成 了 
Kibana 插件 框架 下 的 一 个 默认 app 类 型 插件 。 


本 节 用 以 讲述 Kibana 插件 的 安装 使 用 和 定制 开发 。 


安装 Kibana 插件 有 两 种 方式 : 


1. 通过 Elastic.co 公司 的 下 载 地 址 : 


bin/kibana_plugin --install <org>/<package>/<version> 


version 是 可 选项 。 这 种 方式 目前 适用 于 官方 插件 ， 比 如 : 


bin/kibana plugin -i elasticsearch/marvel/latest 
bin/kibana plugin -i elastic/timelion 


1. 通过 zip 压缩 包 : 


支持 本 地 和 远程 HTTP 下 载 两 种 ， 比 如 : 


bin/kibana_plugin --install sense -u file:///tmp/sense-2.0.0-bet 
ai.tar.gz 

bin/kibana plugin -i heatmap -u https://github.com/stormpython/h 
eatmap/archive/master.zip 

bin/kibana plugin -i kibi timeline vis -u https://github.com/sir 
ensolutions/kibi timeline vis/raw/0.1.2/target/kibi timeline vis 
-0.1.2.zip 

bin/kibana plugin -i oauth2 -u https://github.com/trevan/oauth2/ 
releases/download/0.1.0/0auth2-0.1.0.zip 


目前 已 知 的 Kibana Plugin 列表 见 官方 
WIKI : https://github.com/elastic/kibana/wiki/Known-Plugins 


注意 : kibana 目前 版 本 变动 较 大 ， 不 一 定 所 有 插件 都 可 以 成 功 使 用 


默认 插件 


除了 Kibana 本 身 以 外 ， 其 实 还 有 一 些 其 他 默认 插件 ， 这 些 插件 本 身 在 app 
switcher 页 面 上 是 隐藏 的 ， 但 是 可 以 通过 url 直接 访问 到 ， 或 者 通过 修改 插件 的 
index.js 配置 项 让 它 显示 出 来 。 


这 些 隐藏 的 默认 插件 中 ， 最 有 可 能 被 用 到 的 ， 是 statusPage 插件 。 
我 们 可 以 通过 http://localhost:5601/status 地 址 访问 这 个 插件 的 页 面 : 


Status: Green tsathoggua 


Heap Total (MB)1 1 8.91 Heap Used (MB)QG 80 Load 2.31 ; 2.52, 
2.31 


Response Time Avg1 0 37 Response Time Max 1 40 Requests Per Second() 60 
(ms ^" (ms ' : 


Status Breakdown 





D Status 
ui settings w Ready 
plugin:kibanag 1.0.0 v Ready 
plugin:elasticsearch@1.0.0 v Kibana index ready 
plugin:timelion@5.0.0-alpha4 w Ready 
plugin:console@1.0.0 v Ready 
plugin:kbn_doc_views@1.0.0 w Ready 
plugin:kbn_vislib_vis_types@1.0.0 w Ready 
plugin:markdown_vis@1.0.0 v Ready 
plugin:metric_vis@1.0.0 v Ready 
plugin:spy_modes@1.0.0 w Ready 
plugin:status_page@1.0.0 v Ready 
plugin:table_vis@1.0.0 v Ready 


页 面 会 显示 Kibana 的 运行 状态 。 包 括 nodejs NMA BEA > 5 3X ^ v ELTERE * UR 
各 插件 的 加 载 情况 。 


Kibana4 可 视 化 插件 开发 


上 一 节 ， 我 们 看 到 了 一 个 完整 的 Kibana 插件 的 官方 用 例 。 一 般 来 说 ， 我 们 不 太 会 
需要 自己 从 头 到 尾 写 一 个 angular app 出 来 。 最 常见 的 情况 ， 应 该 是 在 Kibana 功 
能 的 基础 上 做 一 定 的 二 次 开发 和 扩展 。 其 中 ， 可 视 化 效果 应 该 是 重 中 之 重 。 本 节 ， 
以 一 个 红绿灯 效果 ， 演 示 如 何 开 发 一 个 Kibana 可 视 化 插件 。 


Average upstream_time 


La 





插件 目录 生成 


Kibana 开发 组 提供 了 一 个 简单 的 工具 ， 辅 助 我 们 生成 一 个 Kibana 插件 的 目录 结 
构 : 


npm install -g yo 

npm install -g generator-kibana-plugin 
mkdir traffic_light_vis 

cd traffic_light_vis 

yo kibana-plugin 


但 是 这 个 是 针对 完整 的 app 扩展 的 ， 很 多 目录 对 于 可 视 化 插件 来 说 ， 并 没有 用 。 所 
以 ， 我 们 可 以 自己 手动 创建 目录 : 


mkdir -p traffic_light_vis/public 

cd traffic_light_vis 

touch index.js package.json 

cd public 

touch traffic_light_vis.html traffic_light_vis.js traffic_light_ 


vis.less traffic light vis controller.js traffic light vis param 
s. html 


其 中 index.js 内 容 如 下 : 


'use strict'; 
module.exports = function (kibana) ( 
return new kibana.Plugin({ 
uiExports: ( 
visTypes: ['plugins/traffic light vis/traffic light 
MIS] 


3); 
d 


package.json 内 容 如 下 : 


"names: atraf reatet Visi 

VERSION = "0-197. 

"description": "An awesome Kibana plugin for red/yellow/gree 
n status visualize" 


} 


这 两 个 基础 文件 格式 都 比较 固定 ， 除 了 改 个 名 就 基本 OK 了 。 


然后 我 们 看 最 关键 的 可 视 化 对 象 定 义 public/traffic_light_vis.js "€: 


define(function (require) { 
// 加 载 样式 表 
require('plugins/traffic light vis/traffic light vis.less'); 
// 加 载 控制 器 程序 


可 视 化 开发 示例 


require('plugins/traffic light vis/traffic light vis controlle 
r'); 

// 注册 到 vis types 

require('ui/registry/vis types').register(TrafficLightVisProvi 
der); 


function TrafficLightVisProvider(Private) { 

// TemplateVisType 基 类 ， 适 用 于 基础 的 metric 和 数据 表格 式 的 可 视 化 定 
义 。 实 际 上 ，Kibana4 的 metric vis 和 table vis 就 继承 自 这 个 ， 

// Kibana4 还 有 另 一 个 基 类 叫 VisLibVisType， 其 他 使 用 D3.js 做 可 视 化 
的 ， 继 承 这 个 。 

var TemplateVisType = Private(require('ui/template vis type/ 
TemplateVisType')); 

var Schemas = Private(require('ui/Vis/Schemas')); 


// 模板 化 的 visType 对 象 定 义 ， 用 来 配置 和 展示 
return new TemplateVisType({ 
name: 'traffic light', 
// ZB visualize 选择 列表 里 的 名 称 ， 描 述 ， 小 图 标 
litle: emra fre Light. 
description: 'Great for one-glance status readings, the tr 
affic light visualization expresses in green / yellow / red the 
position of a single value in relation to low and high threshold 
S 
icon: 'fa-car', 
// 可 视 化 效果 模板 页 面 
template: require('plugins/traffic light vis/traffic light 
avis nim); 
params: { 
defaults: { 
fontSize: 60 
ty 
// 编辑 参数 的 页 面 
editor: require('plugins/traffic light vis/traffic light 
.Vis params.html') 
tr 
// 在 编辑 页 面 上 可 以 选择 的 aggregation 类 型 。 
schemas: new Schemas([ 
{ 


group: 'metrics', 
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name: 'metric', 
title: “Metric’, 


min: 1, 
defaults: [ 
{ type: 'count', schema: 'metric' } 
] 
} 
]) 
3): 
} 


// export the provider so that the visType can be required wit 
h Private() 
return TrafficLightVisProvider; 


3); 


然后 就 是 可 视 化 效果 的 模板 页 面 了 ， traffic light vis.html 毫 无 疑问 也 是 一 
个 angular 风格 的 : 


可 视 化 开发 D 示例 


<div ng-controller—"TratficlLightViscontroller® cllass— "traf fie-1i 
ght-vis"> 
<div class="metric-container" ng-repeat="metric in metrics"> 
<div class="traffic-light-container" ng-style="{'width': 
vis .params .width+'px', ‘height’: (2.68 * vis.params.width)+'px' 
jus 
«div class="traffic-light"> 
«div class-"light red" ng-class="{'on': (!vis.pa 
rams.invertScale && metric.value «- vis.params.redThreshold) || 
(vis.params.invertScale && metric.value »- vis.params.redThresho 
ld) }"></div> 
«div class="light yellow" ng-class="{'on': (!vis 
.params.invertScale && metric.value » vis.params.redThreshold && 
metric.value « vis.params.greenThreshold) || (vis.params.invert 
Scale && metric.value « vis.params.redThreshold && metric.value 
> vis.params.greenThreshold) }"></div> 
<div class="light green" ng-class="{'on': (!vis. 
params.invertScale && metric.value >= vis.params.greenThreshold) 
|| (vis.params.invertScale && metric.value <= vis.params.greenT 
hreshold) }"></div> 
</div> 
</div> 
<div>{{metric.label}}</div> 
</div> 
</div> 


这 里 可 以 看 到 : 


1. 把 div 绑 定 到 了 TrafficLightVisController 控制 器 上 ， 这 个 也 是 之 前 在 
js 里 已 经 加 载 过 的 。 

2. 通过 ng-repeat 循环 展示 不 同 的 metric， 也 就 是 说 模板 泻 染 的 时 候 ， 收 到 
的 是 一 个 metrics 数组 。 Mus a] € 

3. eI ， 即 什么 灯亮 什么 灯 灭 ， 通 过 了 vis.params.* 的 运算 
判断 。 这 些 变量 当然 是 在 编辑 页 面 里 设置 的 。 


所 以 下 一 步 看 编辑 页 面 traffic_light_vis_params.html 
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<div class="form-group"> 

<label>Traffic light width - {{ vis.params.width }}px</label> 

<input type="range" ng-model="vis.params.width" class="form-co 
ntrol" min="30" max="120"/> 
</div> 
<div class="form-group"> 

<label>Red threshold <span ng-bind-template="({{!vis.params.in 
vertScale ? 'below':'above'}} this value will be red)"></span></ 
label> 

<input type="number" ng-model="vis.params.redThreshold" class= 
"form-control"/> 
</div> 
<div class="form-group"> 

<label>Green threshold <span ng-bind-template="({{!vis.params. 
invertScale ? 'above':'below')) this value will be green)"></span 
></label> 

<input type-"number" ng-model="vis.params.greenThreshold" class 
="form-control"/> 
</div> 
<div class="form-group"> 

<label> 

<input type="checkbox" ng-model="vis.params.invertScale"> 
Invert scale 

</label> 

</div> 


P I8 
内 容 很 简单 ， 就 是 通过 ng-model 设置 绑 定 变量 ， 跟 之 前 HTML 里 的 联动 。 


最 后 一 步 ， 看 控制 器 traffic light vis controller.js 
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define(function (require) { 


var module = require('ui/modules').get('kibana/traffic light v 
1s [*kT2bana']3 


module.controller('TrafficLightVisController', function ($scop 
e, Private) { 
var tabifyAggResponse = Private(require('ui/agg_response/tab 
iy cabanya) 


var metrics = $scope.metrics = []; 


$scope.processTableGroups = function (tableGroups) { 
tableGroups.tables.forEach(function (table) { 
table.columns.forEach(function (column, i) ( 
metrics.push({ 
label: column.title, 
value: table.rows[0][i] 
3); 
3); 
3); 
3 


$scope.$watch('esResponse', function (resp) ( 
if (resp) { 
metrics.length = 0; 
$scope.processTableGroups(tabifyAggResponse($scope.vis, 
resp) ); 
J 
3): 
3); 
+); 


要 点 在 : 


1. $scope.$watch('esResponse', function(resp){}) 监听 整个 页 面 的 请 求 
响应 ， 在 有 新 数据 过 来 的 时 候 更 新 页 面 效果 ; 
2. agg response/tabify/tabify 把 响应 结果 转换 成 二 维 表格 形式 。 


最 后 加 上 一 段 样式 表 ， 这 里 就 不 贴 了 ， 见 : https://github.com/logzio/kibana- 
visualizations/blob/master/traffic light vis/traffic light vis.less ° 

本 节 介 绍 的 示例 ， 出 自 logzio 官方 博客 和 对 应 的 github 开源 项 目 。logz.io 是 基于 
Kibana4.1 写 的 插件 。 我 这 里 修正 成 了 基于 最 新 Kibana4.3 的 实现 。 


Kibana JE 4 2 mit tPF A 


上 一 节 介 绍 了 如 何 给 Kibana 开发 浏览 器 端的 可 视 化 插件 。 新 版 Kibana J& Kibana3 
比 ， R41 eed node.js 服务 器 端 。 那么 同样 的 ， 也 就 有 了 服务 
器 端的 Kibana 插件 。 最 明显 的 一 个 场景 : 我 们 可 以 在 node.js 里 跑 定 时 器 做 
Elasticsearch 的 告警 逻辑 了 ! 


本 节 示 例 一 个 最 基础 的 Kibana 告警 插件 开发 。 只 演示 基础 的 定时 器 和 Kibana 插件 
规范 ， 实 际 运用 中 ， 肯 定 还 涉及 历史 记录 ， 告 警 项 配置 更 新 等 。 请 读者 不 要 直接 
copy-paste ° 


首先 ， 我 们 尽量 沿袭 Elastic 官方 的 watcher * v4 4 E Be E E o 45312 — x 
引 ， 里 面 是 具体 的 配置 内 容 : 


# curl -XPUT http://127.0.0.1:9200/watcher/watch/error_status -d 


{ 
"trigger": { 
"schedule" : { "interval" : "60" } 
3 
ala oh ee ef 
"search" : ( 
"request" : ( 
"indices" : [ "<logstash-{now/d}>", "<logstash-{now/d-1d 
Pp" J 
"body" : { 
"query" : { 
"filtered" : { 
"query" : { "match" : { "host" : "MacBook-Pro" } 
3 


"filter" : ( "range" : { "@timestamp" : ( "from" 
"now-5m" 3 } 3 


"Condition" : { 


SC 
"Script" : "payload.hits.total > 0" 
} 
3 
"transform" : { 
"search" : f 
"request" : ( 
"indices" : [ "<logstash-{now/d}>", "<logstash-{now/d-1d 
jac ds 
"body" : { 
"query" : { 
"filtered" : { 
"query" : { "match" : { "host" : "MacBook-Pro" } 


ty 
"filter" : { "range" : { "@timestamp" : { "from" 
"now-5m" } } } 


} 
3 
"aggs" : { 
"topn" : { 
"terms" : { 
"field" : "path. raw" 
} 
} 
} 
} 
} 
} 
3 
"actions" : ( 
"email admin" : { 
"throttle period" : "15m", 
"email" : ( 
"to" : "admin@domain", 
"subject" : "Found {{payload.hits.total}} Error Events", 
"priority" : "high", 
"body" : "Top10 paths:\n{{#payload.aggregations.topn.bucke 


ts}}\t{{key}} {{doc_count}}\n{{/payload.aggregations.topn.bucket 
s}}" 


j 
} 1 


我 们 可 以 看 到 ， 跟 原版 的 相 比 ， 只 改动 了 很 小 的 一 些 地 方 : 


1. 为 了 简便 ， interval 固定 写 数值 ， 没 带 s/m/d/H 之 类 的 单位 ; 

2. condition 里 直接 使 用 了 JavaScript， 这 点 也 是 ES 2.x 的 mapping 要 求 跟 
watcher 本 身 有 冲突 的 一 个 地 方 : watcher 的 "ctx.payload.hits.total" : 
{ "gt" : 0 } 这 种 写法 ， 如 果 是 普通 索引 ， 会 因为 字段 名 里 带 . 直接 写 入 
失败 的 ; 

3. 因为 是 在 Kibana 里 面 运行 ， 所 以 从 ES 拿 到 的 只 有 payload( 也 就 是 查询 响 
应 )， 所 以 把 里 面 的 ctx. AMT ° 


好 ， 然 后 创建 插件 : 


cd kibana-4.3.0-darwin-x64/src/plugins 
mkdir alert 


在 自 定义 插件 目录 底下 创建 package.json 描述 : 


"name": "alert", 
"version": "0.0.1" 


以 及 最 终 的 index.js 代码 : 


'use strict'; 

module.exports = function (kibana) ( 
var later = require('later'); 
var _ = require('lodash'); 
var mustache = require('mustache'); 


return new kibana.Plugin({ 
init: function init(server) { 
var client = server.plugins.elasticsearch.client; 


var sched = later.parse.text('every 10 minute'); 
later.setInterval(doalert, sched); 
function doalert() { 
getCount().then(function(resp) { 
getwatcher(resp.count).then(function(resp)( 
..each(resp.hits.hits, function(hit){ 
var watch - hit. source; 
var every - watch.trigger.schedule.interval; 
var watchSched - later.parse.recur().every(every). 
second(); 
var wt = later.setInterval(watching, watchSched); 
function watching() { 
var request = watch.input.search.request; 
var condition = watch.condition.script.script; 
var transform = watch.transform.search.request; 
var actions = watch.actions; 
client .search(request) .then(function(payload) { 
var ret = eval(condition); 
if (ret) { 
client.search(transform).then(function(paylo 
ad) { 


_.each(_.values(actions), function(action) 


if(_.has(action, 'email')) { 
var subject = mustache.render(action.e 
mail.subject, {"payload":payload}); 
var body = mustache.render(action.emai 
l.body, {"payload":payload}); 
console.log(subject, body); 
} 
}); 
}); 


}); 
}); 


} 
function getCount() ( 


return client.count({ 
index: 'watcher', 
type: "watch" 
3); 
} 
function getWatcher(count) { 
return client.search({ 
index: 'watcher', 
type: "watch", 
size:count 


}); 


+); 


其 中 用 到 了 两 个 npm 723% > later 模块 用 来 实现 定时 器 和 crontab 文本 解析 ， 
mustache 模块 用 来 泻 当 邮件 内 容 模 板 ， 这 也 是 watcher 本 身 采 用 的 演 染 模块 。 


需要 安装 一 下 : 


npm install later 
npm install mustache 


然后 运行 ./bin/kibana ， 就 可 以 看 到 终端 上 除了 原 有 的 内 容 以 外 ， 还 会 定期 


出 alert 的 email 内 容 了 。 


要 点 解释 


这 个 极 简 示 例 中 ， 主 要 有 两 段 : 
1. 注册 为 插件 
module.exports = function (kibana) { 


return new kibana.Plugin({ 
init: function init(server) { 


输 


注意 上 一 节 的 可 视 化 插件 ， 这 块 是 : 


module.exports = function (kibana) { 
return new kibana.Plugin({ 
uiExports: { 
visTypes: [ 


1. 引用 ES client 


init: function init(server) { 
var client = server.plugins.elasticsearch.client; 


这 里 通过 调用 server.plugins 来 直接 引用 Kibana 里 其 他 插件 里 的 对 象 。 这 
样 ，alert 插件 就 可 以 跟 其 他 功能 共用 同一 个 ES client， 免 去 单独 配置 自己 的 ES 设 
置 项 和 新 开 网 络 连 接 的 资源 消耗 。 


本 节 代 码 后 续 优化 改进 ， 见 : https://github.com/chenryn/kaae。 项 目 中 还 附带 有 一 
个 spy 式 插件 ， 有 兴趣 的 读者 可 以 继续 学 习 spy 这 类 不 太 常 见 的 插件 扩展 的 用 法 。 


app 开发 


前 面 两 节 ， 我 们 分 别 看 过 了 如 何 开发 可 视 化 部 分 和 服务 器 端 部 分 。 现 在 ， 我 们 把 这 
两 头 综合 起 来 ， 做 一 个 可 以 在 Kibana 菜单 栏 上 切换 使 用 的 ， 完 整 的 app。 就 像 
Kibana 5 默认 分 发 的 timelion 和 console 那样 。 


当然 我 们 这 里 不 会 真 的 特意 搞 CAMERA 的 可 视 化 应 用 。 我 们 只 做 一 个 
Elasticsearch 状态 展示 页 面 就 好 了 。 这 个 方式 正好 可 以 串联 从 前 到 后 的 请 求 、 展 示 
部 分 


app 模块 的 index.js 结构 


我 们 已 经 讲 过 了 在 index.js 中 如 何 使 用 uiExports.visType 和 init » 48 A app 的 
index.js 是 什么 样子 的 呢 ? 


export default function (kibana) { 
return new kibana.Plugin({ 
require: ['elasticsearch'], 


uiExports: { 
app: { 
title: 'Indices', 
description: 'An awesome Kibana plugin', 
main: 'plugins/elasticsearch status/app', 
icon: 'plugins/elasticsearch status/icon.svg' 


3): 


这 个 示例 中 有 两 处 特殊 的 代码 : 


1. require 指令 加 载 了 elasticsearch 模块 ; 这 表示 后 续 我 们 会 用 到 这 个 模 
块 ， 所 以 提前 加 载 好 。 
2. uiExports 中 使 用 了 app 键 值 对 定义 。 其 中 这 几 对 键 值 的 含义 如 下 : 
o title: app 的 名 称 ， 用 来 显示 在 Kibana 左 侧 边栏 上 的 文字 ; 


o icon: app 的 图 表 ， 用 来 显示 在 Kibana 左 侧 边栏 上 的 图 标 ; 
o main: app 的 主 入 口 js 文件 。 


作为 完整 的 app， 自 然 也 还 是 有 服务 器 端的 部 分 。 上 节 已 经 讲 过 ， 在 index.js 中 的 
init 部 分 定义 这 块 : 


return new kibana.Plugin( { 
OA 
init(server, options) { 
server.route(( 
path: '/api/elasticsearch_status/index/{name}', 
method: 'GET', 
handler(req, reply) { 
server.plugins.elasticsearch.callWithRequest(req 
, 'Cluster.state', { 
metric: 'metadata', 
index: req.params.name 
}).then(function (response) { 
reply(response.metadata.indices[req.params.n 
ame] ) ; 


传 入 的 server 参数 ， 我 们 在 上 节 只 是 用 来 获取 了 一 下 ESClient。 这 次 ， 我 们 正式 
使 用 一 些 Hapijs 站 正 的 功能 。 比 如 路 由 。 


这 里 创建 的 是 一 个 可 以 被 GET 方法 访问 的 URL 地 址 
/api/elasticsearch status/index/«index name» 。 对 访问 的 处 理应 答 ， 使 
用 handler 方法 。 


handler 方法 传 入 两 个 参数 : 


e req: 有 关 请 求 的 信息 都 可 以 通过 req 对 象 获取 ， 比 如 路 由 中 捕获 的 <index 
name> 就 可 以 用 req.params.name 来 引用 。 


e reply: 应 答 处 理 的 内 容 通过 reply 返回 。 


然后 采用 server.plugins.elasticsearch.callWithRequest 来 发 送 
Elasticsearch 请 求 ， 通 过 Promise.then 来 异步 返回 最 终 的 reply。 这 部 分 和 上 节 讲 
的 类 似 ， 就 不 展开 了 。 


前 侣 界面 的 app.js 


index.js 和 后 台数 据 已 经 就 绪 ， 下 面 就 是 前 人 台 界 面 展 示 问 题 。 我 们 已 经 在 index.js 
里 定义 过 了 main 文件， 是 app.js。 


The first two lines we will insert into the file are the following: 


import 'ui/autoload/styles'; 

import './less/main.less'; 

import uiRoutes from 'ui/routes'; 
import uiModules from 'ui/modules'; 


import overviewTemplate from './templates/index.html'; 
import detailTemplate from './templates/detail.html'; 


uiRoutes.enable(); 

uiRoutes 

-when('/', { 
template: overviewTemplate, 
controller: 'elasticsearchStatusController', 
controllerAs: 'ctrl' 


}) 


.when('/index/:name', { 
template: detailTemplate, 
controller: 'elasticsearchDetailController', 
controllerAs: 'ctrl' 


3); 


文件 第 一 行 永远 要 是 加 载 ui/autoload/styles 。 这 一 行 的 作用 是 保证 你 的 app 
界面 和 Kibana 总 体 保 持 统一 风格 。 这 也 是 Kibana5 才 有 的 新 内 容 。 


然后 通过 uiRoutes 来 完成 Angular 框架 的 路 由 定义 。 这 方面 在 之 前 的 Kibana 
源码 介绍 中 已 经 反复 出 现 过 。 这 里 我 们 定义 好 路 由 对 应 的 控制 器 和 模板 文件 。 


控制 a2 


作为 一 个 简单 示例 ， 我 们 可 以 直接 在 appjs 里 继续 实现 控制 器 部 分 。 如 果 是 复杂 应 
用 ， 一 般 这 里 可 以 拆 分 成 单独 文件 。 


在 Kibana 中 ， 实 现 控 制 器 的 方式 如 下 : 


uiModules 
.get('app/elasticsearch status') 
.controller('elasticsearchStatusController', function ($http) { 

$http.get('../api/elasticsearch status/indices').then((respo 
nse) => { 

this.indices = response.data; 

3); 

3); 


这 里 采用 的 是 Kibana 框架 已 经 封装 好 的 uiModules.get().controller() » X5 
标准 的 angular.module 省 去 了 一 些 创建 声明 、 依 赖 处 理 之 类 的 工作 。 同 样 也 是 
之 前 的 源码 讲解 里 很 熟悉 的 部 分 了 。 


这 里 作为 和 后 端的 配合 ， 我 们 使 用 Angular 标准 的 $http 来 调用 
../api/elasticsearch status/indices 地 址 。 这 正 是 之 前 我 们 声明 好 的 服务 


页 面 模板 


Angular 模板 语言 也 是 已 经 见 过 很 多 面 的 老 朋 友 了 ， 这 块 我 们 用 最 简单 的 一 个 ng- 
repeat 循环 展示 列表 即 可 。 


完整 app 开 发 示例 


<div class="container"> 
«div class="row"> 
«div class="col-12-sm"> 
<hi>Elasticsearch Status</h1> 
<ul class="indexList"> 
<li ng-repeat="index in ctrl.indices"> 
<a href="#/index/{{index}}">{{ index }}</a> 
</li> 
</ul> 
</div> 
</div> 
</div> 


完毕 。 一 个 带 有 前 后 人 台 乃 至 菜单 栏 的 完整 app 就 是 这 么 简单 : 


1,000 hits New Save Open Share 


uo ` [o 





Selected Fields 
? source 
Available Fields > 


_source 


>» account number: 25 balance: 40,540 firstname: Virginia lastname: Ayala age: 39 gender: F address: 171 
Putnam Avenue employer: Filodyne email: virginiaayala@filodyne.com city: Nicholson state: PA _id: 25 


_type: account _index: bank _score: 1 
> account number: 44 balance: 34,487 firstname: Aurelia lastname: Harding age: 37 gender: M address: 50 
2 Baycliff Terrace employer: Orbalix email: aureliaharding@orbalix.com city: Yardville state: DE _id: 4 


4 _type: account _index: bank _score: 1 


» aceannt numher- QQ halance: 47 150 firetnameas Ratliff laetname: Henth ana» 30 meanders F addreces RAR 
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Kibana 截图 报表 


Elastic Stack 本 身 作 为 一 个 实时 数据 检索 聚合 的 系统 ， 在 定期 报表 方面 ， 是 有 一 定 
劣势 的 。 因 为 基本 上 不 可 能 把 源 数 据 长 期 保存 在 Elasticsearch 集群 中 。 即 便 保 存 
了 ， 为 了 一 些 已 经 成 形 的 数据 ， 再 全 面 查询 一 次 过 久 的 冷 数 据 ， 也 是 有 额外 消耗 
的 。 那 么 ， 对 这 种 报表 数据 的 需求 ， 如 何 处 理 ? 其 实 很 简单 ， 把 整个 Kibana 页 面 
截图 下 来 即 可 。 


FireFox 有 插件 用 来 截 全 网 页 图 。 不 过 如 果 作 为 定期 的 工作 ， 还 是 比较 麻烦 
的 ， 需 要 脚本 化 下 来 。 这 时 候 就 可 以 用 上 phantomjs 软件 了 。 o 是 一 个 基 
于 webkit 引擎 做 的 js 脚本 库 。 可 以 通过 js 程序 操作 webkit 浏览 器 引擎 ， 实 现 各 种 


浏览 器 功能 。 


phantomjs 在 Linux 平台 上 没有 二 进 制 分 发 包 ， 所 以 必须 源 代 码 编译 : 


# yum -y install gcc gcc-c++ make flex bison gperf ruby \ 
openssl-devel freetype-devel fontconfig-devel libicu-devel sql 

ite-devel \ 
libpng-devel libjpeg-devel 

# git clone git://github.com/ariya/phantomjs.git 

# cd phantomjs 

# git checkout 2.0 

# ./build.sh 


想 要 给 kibana 页 面 堆 图 ， 几 行 代码 就 够 了 。 


Kibana3 截屏 代码 


下 面 是 一 个 Kibana3 的 截屏 示例 。 capture-kibana.js 如 下 : 


var page = require('webpage').create(); 


var address = 'http://kibana.example.com/#/dashboard/elasticsear 
ch/h5_view'; 
var output = 'kibana.png'; 


page.viewportSize = { width: 1366, height: 600 }; 
page.open(address, function (status) { 
if (status !== 'success') { 
console.log('Unable to load the address!'); 
phantom.exit(); 
) else { 
window.setTimeout(function () ( 
page.render(output); 
phantom.exit(); 
), 30000); 


3); 


» 
> 


然后 运行 phantomjs capture-kibana.js ^4 就 能 得 到 截图 生成 的 


kibana.png 图 片 了 。 
这 里 两 个 要 点 : 


1. 要 设置 viewportSize 里 的 宽度 ， 否 则 效果 会 变 成 单个 panel 依次 往 下 排 
列 。 

2. 要 设置 setTimeout ， 否 则 在 获取 完 index.html 后 就 直接 返回 了 ， 只 能 看 到 
一 个 大 白板 。 用 phantomjs 截取 angularjs 这 类 单 页 MVC 框架 应 用 时 一 定 要 


设置 这 个 。 


Kibana4 的 截屏 开源 项 目 


Kibana4 的 dashboard 同样 可 以 采取 上 面 Kibana3 的 方式 自己 实现 。 不 过 社区 最 
近 有 人 完成 了 一 个 辅助 项 目 ， 把 截屏 配置 、 历 史记 录 展 示 等 功能 都 界面 化 了 。 项 目 
地 址 见 : https://github.com/parvez/snapshot for kibana ° 


Elastic Stack 4 Hadoop 体系 的 区 别 


Kibana 因 其 丰富 的 图 表 类 型 和 漂亮 的 前 端 界面 ， 被 很 多 人 理解 成 一 个 统计 工具 。 而 
我 个 人 认为 ，ELK 这 一 套 体 系 ， 不 应 该 和 Hadoop 体系 同 质 化 。 定 期 的 离线 报表 ， 
不 是 Elasticsearch 专长 所 在 (多 花费 分 词 、 打 分 这 些 步骤 在 高 负载 压力 环境 上 太 奢 
侈 了 )， 也 不 应 该 由 Kibana 来 完成 (每 次 刷新 都 是 重新 计算 )。Kibana 的 使 用 场景 ， 
应 该 集中 在 两 方面 : 


e 实时 监控 


通过 histogram 面板 ， 配 合 不 同 条 件 的 多 个 queries 可 以 对 一 个 事件 走 很 多 个 
维度 组 合 出 不 同 的 时 间 序 列 走势 。 时 间 序 列 数据 是 最 常见 的 监控 报警 了 。 


e 问题 分 析 


通过 Kibana 的 交互 式 界 面 可 以 很 快 的 将 异常 时 间或 者 事件 范围 缩小 到 秒 级 别 
或 者 个 位 数 。 期 望 一 个 完美 的 系统 可 以 给 你 自动 找到 问题 原因 并 且 解 决 是 不 现 
实 的 ， 能 够 让 你 三 两 下 就 从 TB 级 的 数据 里 看 到 关键 数据 以 便 做 出 判断 就 很 棒 
了 。 这 时 候 ， 一 些 非 histogram 的 其 他 面板 还 可 能 会 体现 出 你 意 想不到 的 价 
值 。 全 局 状态 下 看 似 很 普通 的 结果 ， 可 能 在 你 锁定 某 个 范围 的 时 候 发 生 剧 烈 的 
反方 向 的 变化 ， 这 时 候 你 就 能 从 这 个 维度 去 重点 排查 。 而 表格 面板 则 最 直观 的 
显示 出 你 最 关心 的 字段 ， 加 上 排序 等 功能 。 入 库 前 字段 切 分 好 ， 对 于 排 错 分 析 
B0 sXxS:. 


Splunk 场景 参考 
关于 elk 的 用 途 ， 我 想 还 可 以 参照 其 对 应 的 商业 产品 splunk 的 场景 : 
使 用 Splunk 的 意义 在 于 使 信息 收集 和 处 理智 能 化 。 而 其 操作 智能 化 表现 在 : 


1. 搜索 ， 通 过 下 钻 数据 排查 问题 ， 通 过 分 析 根 本 原因 来 解决 问题 ; 

2. 实时 可 见 性 ， 可 以 将 对 系统 的 检测 和 警报 结合 在 一 起 ， 便 > 于 跟踪 SLA 和 
性 能 问题 : 

3. 历史 分 析 ， 可 以 从 中 找 出 趋势 和 历史 模式 ， 行 为 基线 和 阅 值 ， 生 成 一 致 性 
报告 。 


-- Peter Zadrozny, Raghu Kodali 著 / 唐 宏 ， 陈 健 译 《Splunk 大 数据 分 析 》 


推荐 阅读 


e Elasticsearch 权威 指南 
e 精通 Elasticsearch 

e The Logstash Book 

e Elastic Stack Advent 
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